ii

                              
                              
                              
                      Windows Sockets 2
                       Service Provider
                          Interface
                              
                              
    A Service Provider Interface for Transparent Network
             Programming under Microsoft Windows
                              
                              
                       Revision 20.043
                      December 79, 1994
                              
                          Winsock 2
                              
                              
                              
              Subject to Change Without Notice
                              
                              
                              
                              
                              
                              

                              
                         Disclaimer

Microsoft, Intel, and JSB disclaim all warranties and
liability for the use of this document and the information
contained herein, and assume no responsibility for any
errors which may appear in this document. Microsoft, Intel,
and JSB make no warranty or license regarding the
relationship of this document and the information contained
herein to the intellectual property rights of any party.
Microsoft, Intel, and JSB make no commitment to update the
information contained herein.


           Winsock 2.0 Service Provider Interface
                              
TABLE OF CONTENTS

TABLE OF CONTENTS                                        iii
1. INTRODUCTION                                          1
     1.1 Winsock Specification is a WOSA Component       1
          1.1.1 Winsock 2 DLLs                           1
     1.2 Microsoft Windows and Windows-specific
     extensions                                          2
     1.3 Naming Conventions                              2
2. OVERVIEW                                              3
     2.1 Configuration of Winsock Service Providers      3
          2.1.1 Registry Layout for Windows NT and
          Windows 95                                     3
               2.1.1.1 Providers                         3
               2.1.1.2 Provider-specific Keys            3
          2.1.2 WINSOCK2.INI Layout for Windows 3.1      5
               2.1.2.1 Providers                         6
               2.1.2.2 Provider-specific Sections
               ([Provider-<Provider Key>])               6
     2.2. Service Providers Interface Model              8
     2.3 Initialization of Winsock Service Providers     8
     2.4 Functionality Implemented Within the Winsock
     DLL                                                 9
     2.5 Functionality Implemented by Service Providers  9
     2.6 Differences and Similarities Between Winsock
     API and SPI                                         9
     2.7 Differences Between 32-bit and 16-bit Winsock
     SPI                                                 10
     2.8 Sockets                                         10
          2.8.1 Out-of-band data                         10
          2.8.2 Socket Options                           11
     2.9 Quality of Service (QOS)                        13
          2.9.1 Overall Approach                         13
          2.9.2 The Flow Spec Structure                  14
3. SERVICE PROVIDER INTERFACE REFERENCE                  15
     3.1 Socket Routines                                 15
          3.1.1 WSPBind()                                16
          3.1.2 WSPCloseSocket()                         18
          3.1.3 WSPGetPeerName()                         19
          3.1.4 WSPGetSockName()                         20
          3.1.5 WSPGetSockOpt()                          22
          3.1.6 WSPIoctlSocket()                         27
          3.1.7 WSPListen()                              29
          3.1.8 WSPSelect()                              31
          3.1.9 WSPSetSockOpt()                          34
          3.1.10 WSPShutdown()                           38
          3.1.11 WSPAccept()                             40
          3.1.12 WSPAsyncSelect32()                      43
          3.1.13 WSPCallbackSelect16()                   49
          3.1.14 WSPCancelBlockingCall32()               55
          3.1.15 WSPCleanup()                            57
          3.1.16 WSPConnect()                            59
          3.1.17 WSPEnumNetworkEvents()                  64
          3.1.18 WSPEventSelect()                        66
          3.1.19 WSPIsBlocking32()                       71
          3.1.20 WSPRecv()                               72
          3.1.21 WSPRecvFrom()                           75
          3.1.22 WSPSend()                               78
          3.1.23 WSPSendTo()                             81
          3.1.24 WSPSetBlockingHook32()                  85
          3.1.25 WSPSocket()                             87
          3.1.26 WSPStartup()                            89
          3.1.27 WSPUnhookBlockingHook32()               93
4. Upcalls                                               94
     4.1 WPUCreateSocketHandle()                         95
     4.2 WPUCloseSocketHandle()                          96
     4.3 WPUQuerySocketHandleContext()                   97
     4.4 WPUSetSocketHandleContext()                     98
     4.5 WPUQueueUserAPC32()                             99
     4.6 WPUGetCurrentThreadId32()                       100
5. Installation APIs                                     101
     5.1 WPUInstallProvider()                            101
     5.2 WPUDeinstallProvider()                          102
Appendix A. Error Codes and Header Files                 103
     A.1 Error Codes                                     103
     A.2 Winsock SPI Header File - ws2spi.h              105
Appendix B. Notes for Winsock Service Providers          120
     B.1 Introduction                                    120
     B.2 Winsock SPI Run Time Components                 120
     B.3 Error Codes                                     120
Appendix C. Outstanding Issues                           121
.
{General comments: This is really coming along and you guys
(I assume Keith in particular) have really done some nice
work. The most important thing we need to fix (which I think
must be done before the 12th) is to get the service provider
model established correctly. See my comments in section
2.2.1.2 for details. Other than that, my corrections which
are sprinkled liberally throughout the document are mostly
minor issues. Note that I did suggest appending `32' onto
the names of WSPSelect() as well as a few others. Also, I
would really like to thin down the opens section some so
that we don't distract the larger group onto what are
essentially DLL implementationimplemenation issues. See my
comments at the end of the doc for details.

Sooner or later we are going to have to do a very thorough
and careful editing job on this document so that it always
speaks from the perspective of a service provider interface
spec as opposed to an application programming interface
perspective. I realize that the PII SPI had all of these
same problems, but we still have to fix this. In many places
it is quite obvious that we just did a cut and paste from
the API spec without really fixing all the text
appropriately. This does not need to be done by the 12th,
but we need to nail down a reasonable date by which we will
do this. }
1. INTRODUCTION

This document defines the Service Provider Interface (SPI)
of Windows Socket (Winsock) 2.0. The Winsock SPI specifies
the external interface of a service provider to be
implemented by vendors of network protocol stacks.
Installing a service provider allows Windows applications
written to the Winsock 2 API interface to access the service
provider'scorresponding network protocol stacks. This will
permit one or more applications to have access to multiple
protocol stacks simultaneously.

1.1 Winsock Specification is a WOSA Component

The Winsock network transport services are provided as a
WOSA (Windows Open Services Architecture) component. They
consist of both an application programming interface (API)
used by applications and a service provider interface (SPI)
implemented by service providers. This document is designed
to be a stand-alone reference for Winsock service provider
developers. Readers intending to write network applications
should refer to the document "Windows Socket Interface,
revision 2.0" which describes Winsock 2 API.

Windows Open Service Architecture (WOSA) provides a single-
level interface for connecting front-end applications with
back-end services. The front-end application and back-end
service need not speak each other's language in order to
communicate as long as they both know how to talk to the
WOSA interface. As a result, WOSA allows application
developers and vendors of back-end services to mix and match
applications and services to build solutions that shield
programmers and users from the underlying complexity of the
system. WOSA defines an abstraction layer to heterogeneous
computing resources through the WOSA set of APIs. Because
this set of APIs is extensible, new services and their
corresponding APIs can be added as needed. Applications
written to the WOSA APIs have access not only to all the
various computing environments supported today, but also to
all additional environments as they become available.
Moreover, applications don't have to be modified in any way
to enjoy this support.

Each service recognized by WOSA also has a set of interfaces
that service-provider vendors use to take advantage of the
seamless interoperability that WOSA provides. In order to
provide transparent access for applications, each
implementation of a particular WOSA service simply needs to
support the functions defined by its service-provider
interface.

WOSA uses a Windows dynamic-link library (DLL) that allows
software components to be linked at runtime. In this way,
applications are able to connect to services dynamically. An
application needs to know only the definition of the
interface, not its implementation.
1.1.1 Winsock 2 DLLs

Winsock network services follow the WOSA model. This means
that there exists a Winsock Application Programming
Interface (API), which is the application programmer's
access to network services, a Winsock Service Provider
Interface (SPI) which is implemented by network service
provider vendors, and the Winsock DLL. For 16 bit
applications this DLL is referred to as (WINSOCK2.DLL for 16-
bit applications, while 32 bit applications use WSOCK32.DLL
for 32-bit applications). Note that in Windows 3
environments, only Winsock2.DLL will be available, while
Windows 95 and Windows NT support both DLLs. Winsock 2's
WOSA compliant architecture is illustrated below in See
Figure 111Figure 1Figure 1.


                              
                         Figure 111


1.2 Microsoft Windows and Windows-specific extensions

This SPI is intended to be usable within all implementations
and versions of Microsoft Windows including Windows NT,
Windows 95, Windows 3.11, and Windows 3.1.

Winsock makes provisions for multithreaded Windows
processes. In the non-preemptive Win16 environment, a task
corresponds to a process with a single thread of execution.
In the preemptive Win32 environment, a process contains one
or more threads of execution.
The Microsoft Windows extensions included in PII are
provided to allow application developers to create software
which conforms to the Windows programming model.  It is
expected that this will facilitate 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
PSStartup() and PSCleanup() their use is not mandatory.

1.3 Naming Conventions

The Winsock SPI uses the same naming conventions for
functions, messages, and parameters as those used by the
Winsock API except that all the functions are prefixed by
WSP, which stands for Winsock Service Provider.

SPI functions applicable only specific to a particular
platform end in an identifying suffix. For example,
WSPCallbackSelect16() is applicable only specific to 16-bit
Windows, and WSPAsyncSelect32() is applicable onlyspecific
to 32-bit Windows.

"Upcalls" (utility functions made available by the Winsock
DLL for use by SPI DLLs and installation programs) are
prefixedprevixed by WPU, which stands for Winsock Provider
Upcall.
2. OVERVIEW

2.1 Configuration of Winsock Service Providers

When a service provider is installed, some configuration
information must be added to a configuration database to
give the Winsock DLL required information regarding the
service provider. A service provider vendor must arrange for
this information to be updated as part of the service
provider installation.

Under Windows NT and Windows 95, this configuration
information is stored in the system registry. Under Windows
3.1 and 3.11, this configuration information is stored in
the WINSOCK2.INI file.

2.1.1 Registry Layout for Windows NT and Windows 95

All provider configuration information is stored under the
following registry key:

     HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Win
     sock2
     
Throughout this document, all references to relative subkeys
and values are assumed to exist under this main Winsock2
registry key. For example, any reference to the "Providers"
subkey is actually a reference to the
"HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Winsock
2\Providers" key.

2.1.1.1 Providers

The "Providers" subkey contains one subkey for each
installed service provider. The maximum length of provider
subkey names is 32 characters. These subkeys are created by
any software that installs service providers.

The "ProviderOrder" subkey contains zero or more values used
to locate the active service providers. These values also
establish a priority ordering of service providers. The name
of each value represents an active service provider. For
example:

     \ProviderOrder
          Microsoft TCP/IP = REG_SZ ""
          novlwp = REG_SZ ""
          TC&S = REG_SZ ""
     
2.1.1.2 Provider-specific Keys
{ This section needs some additional thought. PII's view of
the world was that there was some number of service
providers, each of which supported exactly one address
family and one or more different socket types. (PII
basically ignored the protocol value, since it was almost
always specified as zero .) It was generally assumed that
each socket type corresponded to a different protocol (e.g.
UDP vs.vs TCP), but that all of the different protocols or
socket types were supplied by the single DLL referenced in
the provider section. Thus for PII, a standard TCP/IP stack
would show up as one provider that supported two different
socket types (SOCK_STREAM and SOCK_DGRAM).

The WS2 view of the world is that each service provider
encompasses exactly one protocol which is uniquely
identified by its protocol value. I believe there needs to
be a 1:1 mapping between service provider entries and
PROTOCOL_INFO structs returned by WSAEnumProtocols(). As
such we need to make sure that all of the information needed
to create the PROTOCOL_INFO structs appear in the service
provider entries (registry or INI file as appropriate).
Since each service provider entry corresponds to a single
protocol, it naturally supports a single address family as
well. However, in the case of a multi-behaviored protocol
like SPX, there may be more than one possible socket type
value that can be used. It is this socket type value which a
service provider would use to determine which of the
available behaviors an application desires. Thus for
example, a standard TCP/IP stack would show up as two
service providers: one for the UDP protocol and one for the
TCP protocol, even though both such providers refer to the
same service provider DLL.

The descriptions in this section assume the PII model of
service providers which is, I believe, at variance with the
proposed Winsock 2 model. It is very important that we are
all on the same page here and that the SPI document clearly
describes how this works.

Each Winsock service provider must have a unique subkey
under the "Providers" subkey. It is the responsibility of
the service provider to create its provider-specific subkey
at the time it is installed. It is also the responsibility
of the service provider to delete its provider-specific
subkey at the time it is removed. Only the service provider
writes values in its provider-specific subkey. The Winsock
DLL reads only the following values in the provider-specific
subkey. Other values in the subkey are permitted for
internal use by the service provider. This subkey consists,
at a minimum, of the following:

     \Provider\<Provider Name>
     ProviderFilename = REG_SZ "<filename>"
     ProviderDescription = REG_SZ "<Description of the
     provider>"
     ProviderDomain = REG_DWORD <Address family>
     ProviderAddrLength = REG_DWORD <length>
     NumSockets = REG_DWORD <count>  { PII model implied }
     SocketType<index> = REG_DWORD <Socket Type>
     AddressFamily<index> = REG_DWORD <Address Family>
     Protocol<index> = REG_DWORD <Protocol>
     MinimumAddressLength<index> = REG_DWORD <Minimum
     Address Length>
     MaximumAddressLength<index> = REG_DWORD <Maximum
     Address Length>
     ProtocolAttributes<index> = REG_DWORD <Protocol
     Attributes>
     ProtocolSocketDescription<index> = REG_SZ "<Description
     of the protocolsocket>"
     
For example:

\Provider\novlwp
ProviderFilename = REG_SZ "novlwp.WPSP"
ProviderDescription = REG_SZ "Novell LAN WorkPlace for
DOS"
 ProviderDomain = REG_DWORD 2
ProviderAddrLength = REG_DWORD 8
NumSockets = REG_DWORD 3
SocketType0 = REG_DWORD 1
AddressFamily0 = REG_DWORD 2
Protocol0 = REG_DWORD 2
MinimumAddressLength0 = REG_DWORD 16
MaximumAddressLength0 = REG_DWORD 16
ProtocolAttributes0 = REG_DWORD 0x00001066
ProtocolSocketDescription0 = REG_SZ "Stream socket in
INET domain"
SocketType1 = REG_DWORD 2
AddressFamily1 = REG_DWORD 2
Protocol1 = REG_DWORD 2
MinimumAddressLength1 = REG_DWORD 16
MaximumAddressLength1 = REG_DWORD 16
ProtocolAttributes1 = REG_DWORD 0x00001609

     ProtocolSocketDescription1 = REG_DSZ "Dgram socket in
     INET domain"
     SocketType2 = REG_DWORD 3
     AddressFamily2 = REG_DWORD 2
     Protocol2 = REG_DWORD 2
     MinimumAddressLength2 = REG_DWORD 16
     MaximumAddressLength2 = REG_DWORD 16
     ProtocolAttributes2 = REG_DWORD 0x00000109
     ProtocolSocketDescription2 = REG_SZ"Raw socket in INET
     domain"
     
The ProviderFilename value identifies the filename of the
service provider DLL.

The ProviderDescription value is the descriptive text of
this service provider.

The ProviderDomain value specifies the address family
(defined in "ws2spi.h") this provider works with.

The ProviderAddrLength value is the (maximum) length of
addresses (in bytes) used in the address family specified in
ProviderDomain. The length includes the two-byte address
family and the size of the address family specific address.

The NumSockets value indicates how many different types of
sockets are supported, and how many SocketType<index>,
AddressFamily<index>, Protocol<index>, and
ProtocolSocketDescription<index> values appear in the
section.

The SocketType<index> value (one per socket type) identifies
the type of this socket as defined in "ws2spi.h".

The AddressFamily<index> value (one per socket type)
identifies the address family of this socket as defined in
"ws2spi.h".

The Protocol<index> value (one per socket type) identifies
the protocol of this socket as defined in "ws2spi.h".

The MinimumAddressLength<index> value (one per socket type)
specifies the minimum BYTE size of a valid address for this
protocol.

The MaximumAddressLength<index> value (one per socket type)
specifies the maximum BYTE size of a valid address for this
protocol.

The ProtocolAttributes<index> value (one per socket type)
identifies the behavioral characteristics of the protocol.
This value consists of any number of XP_xxx values ORed
together. (The XP_xxx values are defined in the Registration
and Resolution API specification.)

The ProtocolSocketDescription<index> value (one per socket
type) is the descriptive text for this protocolsocket.

In the SocketType<index>, AddressFamily<index>,
Protocol<index>, and ProtocolSocketDescription<index>
values, <index> takes the values from 0 to one less than
<count> (as specified in NumSockets). These values are
created by any software that installs the service provider.
Although all these values must be present, there is no
requirement that they appear in numerical order.

The service provider may include any other values/subkeys in
its subkey which are necessary to fulfill the
responsibilities of the provider as specified in the Winsock
Service Provider Interface Specification, or for other
private configuration purposes.

2.1.2 WINSOCK2.INI Layout for Windows 3.1

The WINSOCK2.INI file contains a wide variety of
information, and two kinds of identifiers are used:

  1.   name-sequence numbers. These numbers simply provide a
     convenient way to index through a list of similar entries in
     a WINSOCK2.INI file section. For example, the list of
     "ProviderKey" entries in the [Providers] section uses the
     names ProviderKey0, ProviderKey1, ProviderKey2, ... as a set
     of easily-indexed names for the entries. The scope of these
     name-sequence numbers is strictly limited to the section in
     which they appear. These numbers are unrelated to anything
     outside the section. They may be completely renumbered
     whenever the WINSOCK2.INI configuration changes.
     
  2.   permanent string identifiers. These strings are
     permanent identifiers for entries. They typically appear in
     several different WINSOCK2.INI file sections to identify a
     relationship between entries in those two sections. For
     example, each provider-specific section ([Provider-<Provider
     key>]) includes the permanent string identifier called
     "provider key" of the provider in the section name. This
     indicates that the entry corresponds to the service provider
     with the matching permanent string identifier in the
     [Providers] section. The scope of these string identifiers
     includes the entire WINSOCK2.INI and persists until such
     identifiers are explicitly changed. Some of these
     identifiers can be retrieved through the Winsock SPI
     interface.
     
2.1.2.1 Providers

The "[Providers]" section of WINSOCK2.INI specifies the
total number of the installed Winsock service providers, and
the provider key for each service provider. This information
is used so that Winsock2.DLL can identify and load each
provider.

These entries in this section have the following format:

     [Providers]
     NumProviders=<count>
     ProviderKey<index>="<Provider Key>"
     
For example:

     [Providers]
     NumProviders=2
     ProviderKey0="novlwp"
     ProviderKey1="FTP"
     
The NumProviders entry indicates how many service providers
are installed, and how many ProviderKey<index> entries
appear in the section. <count> is set to 0 when the Winsock
implementation is initialized; the values are subsequently
updated by any software that installs or removes service
providers.

Each ProviderKey<index> entry (one per provider) specifies
an unique provider key with which the service provider can
identify itself. <index> takes the values from 0 to one less
than <count> (as specified in NumProviders). The maximum
length of the provider key is 32 characters. These entries
are created by any software that installs service providers,
and must be renumbered as providers are deleted. Although
all these entries must be present, there is no requirement
that they appear in numerical order. This provider key is
also used to link parameters in other sections for provider-
specific information.

2.1.2.2   Provider-specific  Sections   ([Provider-<Provider
Key>])

For each Winsock service provider defined in the [Providers]
section, there must be a [Provider-<Provider Key>] section.
The <Provider Key> value is the provider key defined for
that service provider in the corresponding
ProviderKey<index>="<Provider Key>" entry in the [Providers]
section. For example, corresponding to an entry such as
ProviderKey0="novlwp" there would be a section named
[Provider-novlwp].

It is the responsibility of the service provider to create
its provider-specific section in WINSOCK2.INI at the time it
is installed. It is also the responsibility of the service
provider to delete its provider-specific section in
WINSOCK2.INI at the time it is removed. Only the service
provider writes entries in its provider-specific section.
Winsock2.DLL reads only the following entries in the
provider-specific section. Other entries in the section are
permitted for internal use by the service provider. This
section consists, at a minimum, of the following:

     [Provider-<Provider Key>]
     ProviderFilename="<filename>"
     ProviderDescription="<Description of the provider>"
      ProviderDomain=<Address family>
     ProviderAddrLength=<length>
     NumSockets=<count>
     SocketType<index>=<Socket Type>
     AddressFamily<index>=<Address Family>
     Protocol<index>=<Protocol>
     MinimumAddressLength<index>=<Minimum Address Length>
     MaximumAddressLength<index>=<Maximum Address Length>
     ProtocolAttributes<index>=<Protocol Attributes>
     ProtocolSocketDescription<index>="<Description of the
     protocolsocket>"
     
For example:

     [Provider-novlwp]
     ProviderFilename="novlwp.WPSP"
     ProviderDescription="Novell LAN WorkPlace for DOS"
      ProviderDomain=2
     ProviderAddrLength=8
     NumSockets=3
     SocketType0=1
     AddressFamily0=2
     Protocol0=2
     MinimumAddressLength0 = 16
     MaximumAddressLength0 = 16
     ProtocolAttributes0 = 0x00001066
     ProtocolSocketDescription0="Stream socket in INET
     domain"
     SocketType1=2
     SocketDescription1="Dgram socket in INET domain"
     SocketType2=3
     MinimumAddressLength0 = 16
     MaximumAddressLength0 = 16
     ProtocolAttributes0 = 0x00001609
     ProtocolSocketDescription2="Raw socket in INET domain"
     
The ProviderFilename entry identifies the filename of the
service provider DLL.

The ProviderDescription entry is the descriptive text of
this service provider.

The ProviderDomain entry specifies the address family
(defined in "ws2spi.h") this provider works with.

The ProviderAddrLength entry is the (maximum) length of
addresses (in bytes) used in the address family specified in
ProviderDomain. The length includes the two-byte address
family and the size of the address family specific address.

The NumSockets entry indicates how many different types of
sockets are supported, and how many SocketType<index>,
AddressFamily<index>, Protocol<index>, and
ProtocolSocketDescription<index> entries appear in the
section.

The SocketType<index> entry (one per socket type) identifies
the type of this socket as defined in "ws2spi.h".

The AddressFamily<index> entry (one per socket type)
identifies the address family of this socket as defined in
"ws2spi.h".

The Protocol<index> entry (one per socket type) identifies
the protocol of this socket as defined in "ws2spi.h".

The MinimumAddressLength<index> value (one per socket type)
specifies the minimum BYTE size of a valid address for this
protocol.

The MaximumAddressLength<index> value (one per socket type)
specifies the maximum BYTE size of a valid address for this
protocol.

The ProtocolAttributes<index> value (one per socket type)
identifies the behavioral characteristics of the protocol.
This value consists of any number of XP_xxx values ORed
together. (The XP_xxx values are defined in the Registration
and Resolution API specification.)

{Do we need to add a protocol entry as well so that all
three components of the socket() call are represented?}
Absolutely, yes. The omission is a PII artifact. We need
every thing that goes into a PROTOCOL_INFO structstrct since
the DLL implements WSAEnumProtocols() without help from the
service provider itself. In fact, the service provider's DLL
may well not have been loaded yet when WSAEnumProviers() is
invoked, and we certainly do not want to requirereqire it to
be loaded just to implement this function.

The ProtocolSocketDescription<index> entry (one per socket
type) is the descriptive text for this protocolsocket.

In the SocketType<index>, AddressFamily<index>,
Protocol<index>, and ProtocolSocketDescription<index>
entiries, <index> takes the values from 0 to one less than
<count> (as specified in NumSockets). These entries are
created by any software that installs the service provider.
Although all these entries must be present, there is no
requirement that they appear in numerical order.

The service provider may include any other entries in its
section which are necessary to fulfill the responsibilities
of the provider as specified in the Winsock Service Provider
Interface Specification, or for other private configuration
purposes.

2.2. Service Providers Interface Model

Winsock service providers are DLLs with EXPORTED procedure
entry points for the functions defined by the SPI. Service
providers should have their file extension changed from
".DLL" to ".WSP". This requirement is not strict. A service
provider will still operate with the Winsock DLL with any
file extension.

The SPI defines an entry point for each Winsock-specific
function. These procedures are EXPORTED procedures just as
in any DLL. They must be exported by ordinal numbers, as
defined in "ws2spi.h" for each function. The Winsock DLL
calls these Winsock specific entry points once the service
provider is loaded using the standard dynamic linkage
mechanism for calling DLLs.

Although entry points are required to be EXPORTED by name,
loading entry points by name is time-consuming in some
Windows environments.  The SPI includes a function to
retrieve an entire table of SPI entry points, bypassing the
name-oriented entry point loading.  The PII.DLL has the
option of using PSGetProcTable() to load entry points in
environments where this is a useful optimization.
PSGetProcTable() retrieves all the functions defined by the
SPI.

The entry points described above cover the instances in
which the Winsock DLL invokes functions provided by the
service provider. The SPI also defines several circumstances
in which the service provider calls back into the Winsock
DLL to inform the Winsock DLL of varioussome occurrences.

2.3 Initialization of Winsock Service Providers

Over time, different versions may exist for the Winsock
DLLs, applications, and service providers. New versions may
define new features, new fields to data structures and bit
fields, etc. Version numbers therefore indicate how to
interpret various data structures.

To allow optimal mixing and matching of different versions
of applications, versions of the Winsock DLL itself, and
versions of service providers by different vendors, the SPI
provides a version negotiation mechanism for the Winsock DLL
and the service provider. This version negotiation is
handled by WSPStartup(). Basically, the Winsock DLL passes
to the service provider the highest version numbers it is
compatible with. The service provider compares this with its
own supported range of version numbers. If these ranges
overlap, the service provider returns a value within the
overlapping portion of the range as the result of the
negotiation. Usually, this should be the highest possible
value. If the ranges do not overlap, the two parties are
incompatible and the function returns an error.

2.4  Functionality  Implemented  WithinValue  Added  by  the
   Winsock DLL

The major task that the Winsock DLL does is to serve as a
sort of "traffic manager" between service providers and
applications. Consider several different service providers
interacting with the same application. Each Provider
interacts strictly with the Winsock DLL. The Winsock DLL
takes care of merging streams of events from those service
providers into a single stream directed at the application.
It hides the details of arbitration and synchronization over
the data structures holding this single stream. Service
providers are unaware that any of this is happening. They do
not need to be concerned about the details of cooperating
with one another or even the existence of other service
providers. By abstracting the service providers into a
consistent DLL interface, the Winsock DLL can interact with
a variety of providers regardless of the underlying
protocol's implementation technology.

In addition to its major "traffic manager" service, the
Winsock DLL provides a number of other services such as
socket descriptor management (in order to avoid conflicts
and ambiguities between applications and service providers
in order to avoid conflict and among service providers),
parameter validation for Winsock API and Winsock SPI,
version negotiation between applications and the Winsock
DLL, as well as between the Winsock DLL and service
providers. The Winsock DLL also realizes protocol
enumeration, event objects, the shared sockets,
implementation and and the pseudo blocking mechanism for
Windows 3 environments.for any blocking Winsock function
calls. Note that the differences between 16 and 32 bit
versions of Windows with respect to blocking, preemption and
shared address spaces dictates that the mechanisms used to
implement the 16 and 32 bit versions of Winsock 2 DLLs vary
significantly as well. This in turn leads to certain SPI
functions that are applicable only to either 16 or 32 bit
Windows implementations.

{It would be worthwhile to describe the routineg mechanism
here. I.e., when an application invokes a socket-based API
(such as bind()) how does the Winsock DLL route this request
to the appropriate service provider?}
{ I agree that providing a simple example at this point would
be most helpful }

2.5   Functionality  ImplementedValue   Added   by   Service
Providers

The Winsock DLL has no knowledge about how requests to
service providers are realized; this is up to the service
provider implementation. Service providers implement the
actual transport protocol which includes such functions as
support the low-level network-specific aspects of Winsock.
This includes functions such as setting up connections,
transferring data, exercising flow control and error
control, etc. The implementation of such functions may
differs greatly from one provider to another. Service
providers hide the implementation-specific details of how
network operations are accomplished.

To summarize: service providers implement provide the low-
level network-specific protocolsmechanisms. The Winsock DLL
provides the medium-level traffic management that
interconnects these transport protocols mechanisms with
applications. Applications in turn provide the policy of how
these traffic streams and network-specific operations are
used to accomplish the functions desired by the user.

2.6 Differences and Similarities Between Winsock API and SPI

The Winsock SPI is similar to the Winsock API in that all
the basic socket functions appear. Support functions like
htonl(), htons(), ntohl(), ntohs(), inet_addr(), and
inet_ntoa() are implemented in the Winsock DLL, and are not
passed down to SPI.

If an extended version of a function and the original
version of a function both exist in the API, only the
extended version will show up in the SPI. For example,
connect() and WSAConnect() will both map to WSPConnect(),
accept() and WSAAccept() to WSPAccept(), and socket() and
WSASocket() to WSPSocket().

Since error codes are returned along with SPI functions,
equivalents of WSAGetLastError() and WSASetLastError() are
not needed in the SPI.

Shared sockets, socket group member enumeration, and Winsock
service provider enumeration are bothall realized in the
Winsock DLL, thus WSADuplicateSocket(), WSAEnumGroup(), and
WSAEnumProtocolsProviders() do not appear as SPI functions.

2.7 Differences Between 32-bit and 16-bit Winsock SPI

In 32-bit environments the service providers are responsible
for implementing blocking behavior. All blocking hook
related API functions such as WSAIsBlocking(),
WSACancelBlockingCall(), WSASetBlockingHook(), and
WSAUnhookBlockingHook() appear in SPI. All event object
related API functions are implemented as #define macros,
mapping the Winsock event functions to native Win32 event
functions.

In 16-bit environments the Winsock DLL implements all
blocking behavior (as pseudopsuedo blocking), and all SPI
sockets are strictly non-blocking. All the blocking hook
related API functions such as WSAIsBlocking(),
WSACancelBlockingCall(), WSASetBlockingHook(), and
WSAUnhookBlockingHook() dowill not appear in the 16 bit SPI
because the blocking hook implementation iswill be realized
in Winsock2.DLL. Similarly, all the event object related API
functions are also implemented in Winsock2.DLL, e.g.,
WSACreateEvent(), WSACloseEvent(), WSASetEvent(),
WSAResetEvent(), WSAWaitForMultipleEvents(), and
WSAGetOverlappedResult().

2.8 Sockets 2.8 Sockets

See API spec for intorductory text on sockets.

2.8.1 Socket Types

See the API for information on socket types.

2.8.21 Out-of-band data

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 interpretations 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 writers are advised
not to use out-of-band data unless this is required in order
to interoperate with an existing service. Winsock suppliers
are urged to document the out-of-band semantics (BSD or RFC
1122) which their product implements. It is beyond the scope
of this specification to mandate a particular set of
semantics for out-of-band data handling.

Note that the out-of-band data functionality is mainly
inherited from the TCP/IP world, and may not be available to
other communication domains supported by this specification.

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 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 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
sequence 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 intervening data. It is
possible to "peek'' at out-of-band data.

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 section
3.1.3.1.3.1., WSPSetSockOptWSPsetsockopt()). 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 Winsock service
provider will maintain a logical "mark" in the data stream
to indicate the point at which the out-of-band data was
sent. An application can use the SIOCATMARK
WSPIoctlSocketWSPioctlsocket() command (see section
3.1.63.1.63.1.6) 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.

2.8.3 Broadcasting

See the API spec for information on Winsock 2's support for
broadcasting

2.8.42 Socket Options

The socket options supported by Winsock SPI are listed and
described in the pages describing
WSPSetSockOptWSPsetsockopt() and
WSPGetSockOptWSPgetsockopt(). A summary of the available
options and the default value for each is shown in the
following table.

Value            Type    Meaning            Default     Not
                                                        e
SO_ACCEPTCONN    BOOL    Socket is          FALSE       get
                         WSPListenWSPliste  unless a    onl
                         n()ing.            WSPListenW  y
                                            SPlisten()
                                            has been
                                            performed
SO_BROADCAST     BOOL    Socket is          FALSE       (i)
                         configured for
                         the transmission
                         of broadcast
                         messages.
SO_DEBUG         BOOL    Debugging is       FALSE       (i)
                         enabled.
SO_DONTLINGER    BOOL    If true, the       TRUE        
                         SO_LINGER option
                         is disabled.
SO_DONTROUTE     BOOL    Routing is         FALSE       (i)
                         disabled.
SO_FLOWSPEC      char    The flow spec of   NULL        get
                 FAR *   this socket.                   onl
                                                        y
SO_GROUP_FLOWSP  char    The flow spec of   NULL        get
EC               FAR *   the socket group               onl
                         to which this                  y
                         socket belongs.
SO_GROUP_ID      GROUP   The identifier of  NULL        get
                         the group to                   onl
                         which this socket              y
                         belongs.
SO_GROUP_PRIORI  int     The relative       0           (i)
TY                       priority for
                         sockets that are
                         part of a socket
                         group.
SO_KEEPALIVE     BOOL    Keepalives are     FALSE       (i)
                         being sent.
SO_LINGER        struct  Returns the        l_onoff is  
                 linger  current linger     0
                         options.
SO_MAX_MSGDG_SI  unsign  Maximum size of a  Implementa  get
ZE               ed int  message for        tion        onl
                         message-oriented   dependent   y
                         socket types
                         (e.g. DGRAM and
                         DSTREAM). Has no
                         meaning for
                         stream-oriented
                         sockets.
SO_OOBINLINE     BOOL    Out-of-band data   FALSE       
                         is being received
                         in the normal
                         data stream.
SO_PROTOCOL_INF  struct  Description of     Protocol    get
O                PROTOC  protocol info for  dependent   onl
                 OL_INF  protocol that is               y
                 O       bound to this
                         socket.
SO_RCVBUF        int     Buffer size for    Implementa  (i)
                         receives           tion
                                            dependent
SO_REUSEADDR     BOOL    The address to     FALSE       
                         which this socket
                         is bound can be
                         used by others.
SO_SNDBUF        int     Buffer size for    Implementa  (i)
                         sends              tion
                                            dependent
SO_TYPE          int     The type of the    As created  get
                         socket (e.g.       via         onl
                         SOCK_STREAM).      WSPSsocket  y
                                            ()
PVD_CONFIG       char    An opaque data     Implementa  
                 FAR *   structure object   tion
                         containing         dependent
                         configuration
                         information of
                         the service
                         provider.
TCP_NODELAY      BOOL    Disables the       Implementa  
                         Nagle algorithm    tion
                         for send           dependent
                         coalescing.

Notes:
(i)       An implementation may silently ignore this option
          on WSPSetSockOptWSPsetsockopt() and return a
          constant value for WSPGetSockOptWSPgetsockopt(),
          or it may accept a value for
          WSPSetSockOptWSPsetsockopt() and return the
          corresponding value in
          WSPGetSockOptWSPgetsockopt() without using the
          value in any way.

2.9 Quality of Service (QOS)
2.9.1 Overall Approach

The basic QOS mechanism in Winsock descends from the flow
specification (or "flow spec") as described by Craig
Partridge in RFC 1363, dated September 1992. A brief
overview of this concept is as follows:

 Flow specs describe a set of characteristics about a
proposed connection-oriented, unidirectional flow through
the network. An application may associate a pair of flow
specs with a socket at the time a connection request is
made. Flow specs indicate parametrically what level of
service is required and also stipulate whether the
application is willing to be flexible if the requested level
of service is not available. After a connection is
established, the application may retrieve the flow specs
associated with the socket and examine the contents to
discover the level of service that the network is willing
and/or able to provide. If the service provided is not
acceptable, the application may close the socket and take
whatever action is appropriate (e.g. scale back and ask for
a lower quality of service, try again later, notify the user
and exit, etc.)

Even after a flow is established, conditions in the network
may change resulting in a reduction (or increase) in the
available service level. A notification mechanism is
included which utilizes the usual Winsock 2 notification
techniques to indicate to the application that QOS levels
have changed. The app should again retrieve the
corresponding flow specs and examine them in order to
discover what aspect of the service level has changed.

The flow specs proposed for Winsock 2 divide QOS
characteristics into the following general areas:

1.Network bandwidth utilization - The manner in which the
  application's traffic will be injected into the network.
  This includes specifications for average bandwidth
  utilization, peak bandwidth, and maximum burst duration.

2.Latency - Upper limits on the amount of delay and delay
  variation that are acceptable.

3.Level of service guarantee - Whether or not an absolute
  guarantee is required as opposed to best effort. Note
  that providers which have no feasible way to provide the
  level of service requestedrequeted are expected to fail
  the connection attempt.

4.Cost - This is a place holder for a future time when a
  meaningful cost metric can be determined.

5.Provider-specific parameters - The flow spec itself can
  be extended in ways that are particular to specific
  providers, and the assumed provider can be identified.


An application indicates its desire for a non-default flow
spec at the time a connection request is made (see
WSPConnect () and WSPAccept()). Since establishing a flow
spec'd connection is likely to involve cooperation and/or
negotiation between intermediate routers and hosts, the
results of a flow spec request cannot be determined until
after the connection operation is fully completed. After
this time, the application may use getsockopt() to retrieve
the resulting flow spec structure so that it can determine
what the network was willing and/or able to supply.

2.9.2 The Flow Spec Structure

The Winsock 2 flow spec structure is defined in Winsock2.h
and is reproduced here.

typedef enum
{
     GuaranteedService,
     BestEffortService
} GUARANTEE;

typedef struct _flowparams
{
     int64          AverageBandwith;// In Bytes/sec
     int64          PeakBandwidth; // In Bytes/sec
     int64          BurstLength;   // In microseconds
     int64          Latency;  // In microseconds
     int64          DelayVariation;// In microseconds
     GUARANTEE levelOfGuarantee;// Guaranteed or
                         // Best Effort
     int32          CostOfCall;    // Reserved for future
                         // use, must be set to 0
     int32          ProviderId;    // Provider Identifier
     int32          SizePSP;  // Length of provider
                         // specific parameters
          UCHAR     ProviderSpecificParams[1];// provider
specific                                          //
parameters
} FLOWPARAMS;

typedef struct _QualityOfService
{
     FLOWPARAMS     ForwardFP;     // Caller(Initiator) to
callee
     FLOWPARAMS     BackwardFP;    // Callee to caller
} QOS, FAR * LPQOS;
3. SERVICE PROVIDER INTERFACE REFERENCE

3.1 Socket Routines

This chapter presents the service provider socket library
routines in alphabetical order, and describes each routine
in detail.
{ Since the SPI is new, I propose that we do not have
separate sections for Windows-specific extensions}

In each routine it is indicated that the header file
ws2spi.h must be included. Appendix A.2 lists the Berkeley-
compatible header files which are supported.  These are
provided for compatibility purposes only, and each of them
will simply include PII.h. The Windows header file windows.h
is also needed, but ws2spi.h will include it if necessary.
3.1.1 PSaccept()
Description    Accept a connection on a socket.

          #include <PIISPI.h>

          SOCKET PASCAL FAR PSaccept ( SOCKET s, struct
          sockaddr FAR * addr,
          int FAR * addrlen, int FAR * lpErrno );

          
          s          A descriptor identifying a socket which
                    is listening for connections after a
                    PSlisten().
          
          addr      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 addr
                    argument is determined by the address
                    family established when the socket was
                    created.
          
          addrlen   An optional pointer to an integer which
                    contains the length of the address addr.
          
          lpErrno   A pointer to the error code.

Remarks   This routine extracts the first connection on the
          queue of pending connections on s, creates a new
          socket with the same properties as s except not in
          the listening state, 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, PSaccept() blocks the caller until a
          connection is present.  If the socket is marked
          non-blocking and no pending connections are
          present on the queue, PSaccept() returns an error
          as described below.  The accepted socket may not
          be used to accept more connections.  The original
          socket remains open.

          The argument addr is a result parameter that is
          filled in with the address of the connecting
          entity, as known to the communications layer.  The
          exact format of the addr parameter is determined
          by the address family in which the communication
          is occurring.  The addrlen is a value-result
          parameter; it should initially contain the amount
          of space pointed to by addr; on return it will
          contain the actual length (in bytes) of the
          address returned.  This call is used with
          connection-oriented socket types such as
          SOCK_STREAM.  If addr and/or addrlen are equal to
          NULL, then no information about the remote address
          of the accepted socket is returned.

Return Value   If no error occurs, PSaccept() 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 is available in lpErrno.

          The integer referred to by addrlen initially
          contains the amount of space pointed to by addr.
          On return it will contain the actual length in
          bytes of the address returned.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The addrlen argument is too
                              small (less than the sizeof a
                              struct sockaddr).
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              PSCancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII call is in
                              progress.
          
          WSAEINVAL           PSlisten() was not invoked
                              prior to PSaccept().
          
          WSAEMFILE           The queue is non-empty upon
                              entry to PSaccept() and there
                              are no descriptors available.
          
          WSAENOBUFS          No buffer space is available.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       The referenced socket is not a
                              type that supports connection-
                              oriented service.
          
          WSAEWOULDBLOCK      No connections are present to
                              be accepted.
          
See Also  PSbind(), PSconnect(), PSlisten(), PSselect(),
          PSsocket(), PSCallbackSelect()

3.1.1 WSPBindWSPbind()

Description    Associate a local address with a socket.

          #include <ws2spi.h>

          int WSPAPI WSPBindWSPbind ( SOCKET s, const struct
          sockaddr FAR * name, int namelen, int FAR *
          lpErrno );

          
          s          A descriptor identifying an unbound
                    socket.
          
          name      The address to assign to the socket. The
                    sockaddr structure is defined as
                    follows:
          
                    struct sockaddr {
                         u_short   sa_family;
                         char      sa_data[14];
                    };
          
          namelen   The length of the name.
          
          lpErrno   A pointer to the error code.

Remarks   This routine is used on an unconnected
          connectionless or connection-oriented socket,
          before subsequent WSPConnect()s or
          WSPListenWSPlisten()s. When a socket is created
          with WSPsocket(), it exists in a name space
          (address family), but it has no name assigned.
          WSPBindWSPbind() establishes the local association
          of the socket by assigning a local name to an
          unnamed socket.
          
          As an example, in the Internet address family, a
          name consists of three parts: the address family,
          a host address, and a port number which identifies
          the application. In Winsock 2, the name parameter
          is not strictly interpreted as a pointer to a
          "sockaddr" struct. It is cast this way for Windows
          Sockets 1.1 compatibility. Service providers are
          free to regard it as a pointer to a block of
          memory of size namelen. The first two bytes in
          this block (corresponding to "sa_family" in the
          "sockaddr" declaration) must contain the address
          family that was used to create the socket.
          Otherwise an error WSAEFAULT will occur.
          
Return Value   If no error occurs, WSPBindWSPbind() returns
          0. Otherwise, it returns SOCKET_ERROR, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       The specified address is
                              already in use. (See the
                              SO_REUSEADDR socket option
                              under
                              WSPSetSockOptWSPsetsockopt().)
          
          WSAEFAULT           The namelen argument is too
                              small (less than the size of a
                              struct sockaddr), the name
                              argument contains incorrect
                              address format for the
                              associated address family, or
                              the first two bytes of the
                              memory block specified by name
                              does not match the address
                              family associate with the
                              socket descriptor s.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEAFNOSUPPORT     The specified address family
                              is not supported by this
                              protocol.
          
          WSAEINVAL           The socket is already bound to
                              an address.
          
          WSAENOBUFS          Not enough buffers available,
                              too many connections.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

See Also  WSPConnect(), WSPListenWSPlisten(),
          WSPGetSockNameWSPgetsockname(),
          WSPSetSockOptWSPsetsockopt(), WSPsocket(),
          PSCancelBlockingCall().
3.1.2 WSPCloseSocketWSPclosesocket()

Description    Close a socket.

          #include <ws2spi.h>

          int WSPAPI WSPCloseSocketWSPclosesocket ( SOCKET
          s, int FAR * lpErrno );

          
          s          A descriptor identifying a socket.
          
          lpErrno   A pointer to the error code.

Remarks   This function closes a socket. More precisely, it
          releases the socket descriptor s, so that further
          references to s will fail with the error
          WSAENOTSOCK.  If this is the last reference to an
          underlying socket, the associated naming
          information and queued data are discarded.
          
          The semantics of WSPCloseSocketWSPclosesocket()
          are affected by the socket options SO_LINGER and
          SO_DONTLINGER as follows:

          Option         Interval       Type of close  Wait
                    for close?
          SO_DONTLINGER  Don't care     Graceful       No
          SO_LINGER      Zero      Hard      No
          SO_LINGER      Non-zero  Graceful       Yes

          If SO_LINGER is set (i.e. the l_onoff field of the
          linger structure is non-zero; see sections
          3.1.53.1.53.1.5 and 3.1.3.1.3.1.) with a zero
          timeout interval (l_linger is zero),
          WSPCloseSocketWSPclosesocket() is not blocked even
          if queued data has not yet been sent or
          acknowledged. This is called a "hard" or
          "abortive" close, because the socket's virtual
          circuit is reset immediately, and any unsent data
          is lost. Any WSPRecvWSPrecv() call on the remote
          side of the circuit will fail with WSAECONNRESET.
          
          If SO_LINGER is set with a non-zero timeout
          interval, the PSclosesocket() call blocks until
          the remaining data has been sent or until the
          timeout expires.  This is called a graceful
          disconnect.  Note that if the socket is set to non-
          blocking and SO_LINGER is set to a non-zero
          timeout, the call to PSclosesocket() will fail
          with an error of WSAEWOULDBLOCK.

          If SO_DONTLINGER is set on a stream socket (i.e.
          the l_onoff field of the linger structure is zero;
          see sections 3.1.53.1.53.1.5 and 3.1.3.1.3.1.),
          the WSPCloseSocketWSPclosesocket() 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
          Winsock service provider may not release the
          socket and other resources for an arbitrary
          period, which may affect applications which expect
          to use all available sockets.

Return Value   If no error occurs,
          WSPCloseSocketWSPclosesocket() returns 0.
          Otherwise, a value of SOCKET_ERROR is returned,
          and a specific error code is available in lpErrno.
          
Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
See Also  WSPAccept, WSPsocket(),
          WSPIoctlSocketWSPioctlsocket(),
          WSPSetSockOptWSPsetsockopt().
3.1.4 PSconnect()
Description    Establish a connection to a peer.

          #include <PIISPI.h>

          int PASCAL FAR PSconnect ( SOCKET s, const struct
          sockaddr FAR * name,
          int namelen, int FAR * lpErrno );

          
          s          A descriptor identifying an unconnected
                    socket.
          
          name      The name of the peer to which the socket
                    is to be connected.
          
          namelen   The length of the name.
          
          lpErrno   A pointer to the error code.

Remarks   This function is used to create a connection to
          the specified destination.  For connection-
          oriented sockets (e.g., type SOCK_STREAM), an
          active connection is initiated to the foreign host
          using name (an address in the name space of the
          socket; for a detailed description, please see
          PSbind()).  When the socket call completes
          successfully, the socket is ready to send/receive
          data.
          
          For a connectionless socket (e.g., type
          SOCK_UNREL_DGRAM), the operation performed by
          PSconnect() is merely to establish a default
          destination address which will be used on
          subsequent PSsend() and PSrecv() calls.
          
          If the socket, s, 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 name structure is all
          zeroes, PSconnect() will return the error
          WSAEADDRNOTAVAIL.
          

Return Value   If no error occurs, PSconnect() returns 0.
          Otherwise, it returns SOCKET_ERROR, and a specific
          error code is available in lpErrno.

          On a non-blocking socket,If the return value is
          SOCKET_ERROR an application should call
          PSGetLastError().  For connection-oriented
          sockets, if the return value is 0, indicating the
          connect operation has been successfully initiated,
          then your application can either:
          
          1. Use PSselect() to determine the completion of
          the connection request by checking if the socket
          is writeable,  or
          
          2. If your application is using PSCallbackSelect()
          to indicate interest in connection events, then
          your application will receive an FD_CONNECT
          callback when the connect operation is complete.

Error Codes    The following errors may occur at the time of
          the function call, and indicate that the connect
          operation could not be initiated.

WSANOTINITIALISED             A successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              PSCancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII call is in
                              progress.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAEDESTADDREQ      A destination address is
                              required.
          
          WSAEFAULT           The namelen argument is
                              incorrect.
          
          WSAEINVAL           The socket is not already
                              bound to an address.
          
          WSAEISCONN          The socket is already
                              connected.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEWOULDBLOCK      The socket is marked as non-
                              blocking and the connection
                              cannot be completed
                              immediately.  It is possible
                              to PSselect() the socket while
                              it is connecting by
                              PSselect()ing it for writing.


          The following error codes may be set when the
          callback function is invoked.

WSANOTINITIALISED             A successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              PSCancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII call is in
                              progress.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAECONNREFUSED     The attempt to connect was
                              forcefully rejected.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAETIMEDOUT        Attempt to connect timed out
                              without establishing a
                              connection
          
See Also  PSaccept(), PSbind(), PSgetsockname(), PSsocket(),
          PSselect()PSCallbackSelect(), PSConnectEx().
3.1.3 WSPGetPeerNameWSPgetpeername()

Description    Get the address of the peer to which a socket
          is connected.

          #include <ws2spi.h>

          int WSPAPI WSPGetPeerNameWSPgetpeername ( SOCKET
          s, struct sockaddr FAR * name, int FAR * namelen,
          int FAR * lpErrno );

          
          s          A descriptor identifying a connected
                    socket.
          
          name      The structure which is to receive the
                    name of the peer.
          
          namelen   A pointer to the size of the name
                    structure.
          
          lpErrno   A pointer to the error code.

Remarks   WSPGetPeerNameWSPPSgetpeername() retrieves the
          name of the peer connected to the socket s and
          stores it in the struct sockaddr identified by
          name. It is used on a connected datagram or stream
          socket.

          On return, the namelen argument contains the
          actual size of the name returned in bytes.

Return Value   If no error occurs,
          WSPGetPeerNameWSPgetpeername() returns 0.
          Otherwise, a value of SOCKET_ERROR is returned,
          and a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The namelen argument is not
                              large enough.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTCONN         The socket is not connected.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

See Also  WSPBindWSPPSbind(), WSPsocket(),
          WSPGetSockNameWSPgetsockname().
3.1.4 WSPGetSockNameWSPgetsockname()

Description    Get the local name for a socket.

          #include <ws2spi.h>

          int WSPAPI WSPGetSockNameWSPgetsockname ( SOCKET
          s, struct sockaddr FAR * name,
          int FAR * namelen, int FAR * lpErrno );

          
          s          A descriptor identifying a bound socket.
          
          name      Receives the address (name) of the
                    socket.
          
          namelen    The size of the name buffer.
          
          lpErrno   A pointer to the error code.

Remarks   WSPGetSockNameWSPPSgetsockname() retrieves the
          current name for the specified socket descriptor
          in name. It is used on a bound and/or connected
          socket specified by the s parameter. The local
          association is returned. This call is especially
          useful when a WSPConnect() call has been made
          without doing a WSPBindWSPbind() first; as this
          call provides the only means by which the local
          association which has been set by the service
          provider can be determinedyou can determine the
          local association which has been set by the
          system.

          On return, the namelen argument contains the
          actual size of the name returned in bytes.
          
          If a socket was bound to an unspecified address
          (e.g., ADDR_ANY), indicating that any of the
          host's addresses within the specified address
          family should be used for the socket,
          WSPGetSockNameWSPgetsockname() will not
          necessarily return information about the host
          address, unless the socket has been connected with
          WSPConnect() or WSPAccept. The Winsock DLL must
          not assume that the address will be specified
          unless the socket is connected. This is because
          for a multi-homed host the address that will be
          used for the socket is unknown unless the socket
          is connected.

Return Value   If no error occurs,
          WSPGetSockNameWSPgetsockname() returns 0.
          Otherwise, a value of SOCKET_ERROR is returned,
          and a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The namelen argument is not
                              large enough, or the name or
                              namelen argument is not part
                              of the user address space.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEINVAL           The socket has not been bound
                              to an address with
                              WSPBindWSPbind(), or ADDR_ANY
                              is specified in
                              WSPBindWSPbind() but
                              connection has not yet occurs.

See Also  WSPBindWSPPSbind(), WSPsocket(),
          WSPGetPeerNameWSPgetpeername().
3.1.5 WSPGetSockOptWSPgetsockopt()

Description    Retrieve a socket option.

          #include <ws2spi.h>

          int WSPAPI WSPGetSockOptWSPgetsockopt ( SOCKET s,
          int level, int optname,
          char FAR * optval, int FAR * optlen, int FAR *
          lpErrno );

          
          s          A descriptor identifying a socket.
          
          level     The level at which the option is
                    defined; the only supported levels are
                    SOL_SOCKET and SOL_PROVIDER.
                    (SOL_PROVIDER is defined to be an alias
                    for IPPROTO_TCP for the sake of
                    compatibility with Windows Sockets
                    specification 1.1.)
          
          optname   The socket option for which the value is
                    to be retrieved.
          
          optval    A pointer to the buffer in which the
                    value for the requested option is to be
                    returned.
          
          optlen    A pointer to the size of the optval
                    buffer.
          
          lpErrno   A pointer to the error code.

Remarks   WSPGetSockOptWSPPSgetsockopt() retrieves the
          current value for a socket option associated with
          a socket of any type, in any state, and stores the
          result in optval. 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 or not, the routing of packets, out-of-band
          data transfer, etc.

          The value associated with the selected option is
          returned in the buffer optval. The integer pointed
          to by optlen 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 most other
          options it will be the size of an integer.
          
          The Winsock DLL is responsible for allocating any
          memory space pointed to directly or indirectly by
          any of the parameters it specifiesd.
          
          If the option was never set with
          WSPSetSockOptWSPsetsockopt(), then
          WSPGetSockOptWSPgetsockopt() returns the default
          value for the option.
          
level = SOL_SOCKET                       
Value                            Type    Meaning
SO_ACCEPTCONN                    BOOL    Socket is
                                         WSPListenWSPlisten()ing.
SO_BROADCAST                     BOOL    Socket is configured for
                                         the transmission of
                                         broadcast messages.
SO_DEBUG                         BOOL    Debugging is enabled.
SO_DONTLINGER                    BOOL    If true, the SO_LINGER
                                         option is disabled.
SO_DONTROUTE                     BOOL    Routing is disabled.
SO_FLOWSPEC                      char    The flow spec of this
                                 FAR *   socket.
SO_GROUP_FLOWSPEC                char    The flow spec of the
                                 FAR *   socket group to which this
                                         socket belongs.
SO_GROUP_ID                      GROUP   The identifier of the
                                         group to which this socket
                                         belongs.
SO_GROUP_PRIORITY                int     The relative priority for
                                         sockets that are part of a
                                         socket group.
SO_KEEPALIVE                     BOOL    Keepalives are being sent.
SO_LINGER                        struct  Returns the current linger
                                 linger  options.
SO_MAX_MSGDG_SIZE                unsigne Maximum size of a message
                                 d int   for message-oriented
                                         socket types (e.g. DGRAM
                                         and DSTREAM). Has no
                                         meaning for stream-
                                         oriented sockets.
SO_OOBINLINE                     BOOL    Out-of-band data is being
                                         received in the normal
                                         data stream.
SO_PROTOCOL_INFO                 struct  Description of protocol
                                 PROTOCO info for protocol that is
                                 L_INFO  bound to this socket.
SO_RCVBUF                        int     Buffer size for receives
SO_REUSEADDR                     BOOL    The socket may be bound to
                                         an address which is
                                         already in use.
SO_SNDBUF                        int     Buffer size for sends
SO_TYPE                          int     The type of the socket
                                         (e.g. SOCK_STREAM).
                                         
level = SOL_PROVIDER                     
 (also aliased to IPPROTO_TCP)
PVD_CONFIG                       Service An "opaque" data structure
                                 Provide object from the service
                                 r       provider associated with
                                 Depende socket s. This object
                                 nt      stores the current
                                         configuration information
                                         of the service provider.
                                         The exact format of this
                                         data structure is service
                                         provider specific.
TCP_NODELAY                      BOOL    Disables the Nagle
                                         algorithm for send
                                         coalescing.
               
               BSD options not supported for
               WSPGetSockOptWSPgetsockopt() are:
               
Value                       Type     Meaning
SO_ERROR                    int      Get error status and clear
SO_RCVLOWAT                 int      Receive low water mark
SO_RCVTIMEO                 int      Receive timeout
SO_SNDLOWAT                 int      Send low water mark
SO_SNDTIMEO                 int      Send timeout
IP_OPTIONS                           Get options in IP header.
TCP_MAXSEG                  int      Get TCP maximum segment
                                     size.

          Calling WSPGetSockOptWSPgetsockopt() with an
          unsupported option will result in an error code of
          WSAENOPROTOOPT being returned in lpErrno.
          
     SO_DEBUG
          Winsock service providers 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
          specification.
          
     SO_FLOWSPEC
          This is a get-only socket option which indicates
          the flow spec of the socket. The default flow spec
          defined in Sec. 2.8.3 will be returned before the
          application sets the flow spec for this socket.
          The WSAENOPROTOOPT error code is indicated for
          service providers which do not support the flow
          spec option. See WSPConnect() about how to set the
          flow spec.
          
     SO_GROUP_FLOWSPEC
          This is a get-only socket option which indicates
          the flow spec of the group this socket belongs to.
          The default flow spec defined in Sec. 2.8.3 will
          be returned before the application sets the flow
          spec for this socket group. The WSAENOPROTOOPT
          error code is indicated for service providers
          which do not support the group flow spec option.
          If this socket does not belong to an appropriate
          socket group, the Flen and Blen fields of the
          returned QOS struct are set to 0. See WSPConnect()
          about how to set the flow spec.
          
     SO_GROUP_ID
          This is a get-only socket option which indicates
          the identifier of the group this socket belongs
          to. If this socket is not a group socket, the
          value is NULL.
          
          The group option is provided as a way to
          facilitate the formation of multiplex
          relationships between two or more sockets (each
          with the group option set) that will share an
          underlying physical connection.  While such
          multiplexing is an assumed attribute of packet
          switched networks, the assumption does not
          necessarily hold true for circuit switched
          networks.  By setting this option, the application
          indicates a preference for eligible sockets to be
          multiplexed together.
          
     SO_GROUP_PRIORITY
          Group priority indicates the relative priority of
          the specified socket relative to other sockets
          within the socket group. Values are non-negative
          integers, with zero corresponding to the highest
          priority. Priority values represent a hint to the
          underlying service provider about how potentially
          scarce resources should be allocated. For example,
          whenever two or more sockets are both ready to
          transmit data, the highest priority socket (lowest
          value for SO_GROUP_PRIORITY) should be serviced
          first, with the remainder serviced in turn
          according to their relative priorities.
          
          The WSAENOPROTOOPT error code is indicated for non
          group sockets or for service providers which do
          not support group sockets.
          
     SO_KEEPALIVE
          An application may request that a TCP/IP service
          provider enable the use of "keep-alive" packets on
          TCP connections by turning on the SO_KEEPALIVE
          socket option. A Winsock provider 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:
          Requirements for Internet Hosts -- Communication
          Layers. 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.
          
     SO_LINGER
          SO_LINGER controls the action taken when unsent
          data is queued on a socket and a
          WSPCloseSocketWSPclosesocket() is performed. See
          WSPCloseSocketWSPclosesocket() for a description
          of the way in which the SO_LINGER settings affect
          the semantics of WSPCloseSocketWSPclosesocket().
          The application gets the desired behavior by
          creating a struct linger (pointed to by the optval
          argument) with the following elements:
          
          struct linger {
               int  l_onoff;
               int  l_linger;
          }
          
          
          To enable SO_LINGER, the application should set
          l_onoff to a non-zero value, set l_linger to 0 or
          the desired timeout (in seconds), and call
          PSsetsockopt().  To enable SO_DONTLINGER (i.e.
          disable SO_LINGER) l_onoff should be set to zero
          and PSsetsockopt() should be called.
          
     SO_MAX_MSGDG_SIZE
          This is a get-only socket option which indicates
          the maximum size of a message for message-oriented
          socket types (e.g. DGRAM or DSTREAM) as
          implemented by a particular service provider. It
          has no meaning for byte stream oriented sockets
          
     SO_RESERVED_BW and SO_AVAILABLE_BW
          These options are used primarily with isochronous
          sockets, although both options have meaningful
          interpretations for non-isochronous sockets as
          well.  When dealing with isochronous sockets, the
          application may retrieve the value of
          SO_AVAILABLE_BW to determine the maximum amount of
          bandwidth that is available to be reserved.  It
          uses SO_RESERVED_BW to actually request bandwidth
          allocation or to determine the current bandwidth
          already allocated to the socket.  In both
          instances, bandwidth values are expressed in "bits
          per second (bps)".
          
          For non-isochronous sockets, the value of
          SO_AVAILABLE_BW is used to provide a hint as to
          the relative capacity of the underlying network.
          Applications may wish to know, for example,
          whether they are running over a 1200 baud serial
          line or a 155 Mbps ATM link. Since in many
          instances it is impossible for a non-isochronous
          service provider to supply a precise value for
          this option, applications must realize that the
          supplied value may represent nothing more than a
          reasonable approximation of the capacity of the
          underlying network.  Applications may likewise use
          the value of SO_RESERVED_BW to provide a hint to
          the service provider about the desired amount of
          bandwidth.
          
     SO_REUSEADDR
          By default, a socket may not be bound (see
          WSPBindWSPbind()) to a local address which is
          already 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 local address as long as the remote
          addresses are different. To inform the Winsock
          provider that a WSPBindWSPbind() on a socket
          should not be disallowed because the desired
          address is already in use by another socket, the
          application should set the SO_REUSEADDR socket
          option for the socket before issuing the
          WSPBindWSPbind(). Note that the option is
          interpreted only at the time of the
          WSPBindWSPbind(): 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
          WSPBindWSPbind() has no effect on this or any
          other socket.
          
     PVD_CALL_ID
          This is a get-only socket option which corresponds
          to an opaque Winsock call ID used for
          Winsock/Telephony Integration. See Appendix C for
          details. Winsock service providers which are not
          also TAPI service providers should return an
          WSAENOPROTOOPT error code when this option's value
          is requested.
          
     PVD_CONFIG
          This option retrieves an "opaque" data structure
          object from the service provider associated with
          socket s. This object stores the current
          configuration information of the service provider.
          The exact format of this data structure is service
          provider specific.
          
     TCP_NODELAY
          The TCP_NODELAY 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 impede
          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
          performance.
          
     TAPI_DEVICE_ID
          This is a get-only socket option which corresponds
          to a line device ID for Windows Telephony API
          (TAPI). See Appendix C for details. Winsock
          service providers which are not also TAPI service
          providers should return an WSAENOPROTOOPT error
          code when this option's value is requested.

Return Value   If no error occurs,
          WSPGetSockOptWSPgetsockopt() returns 0. Otherwise,
          a value of SOCKET_ERROR is returned, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The optlen argument was
                              invalid.
          
          WSAEINVAL           No value available for optname
                              at the moment.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOPROTOOPT      The option is unknown or
                              unsupported by the indicated
                              protocol family.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

See Also  WSPSetSockOptWSPPSsetsockopt(),WSPsocket().
3.1.6 WSPIoctlSocketWSPioctlsocket()

Description    Control the mode of a socket.

          #include <ws2spi.h>

          int WSPAPI WSPIoctlSocketWSPioctlsocket ( SOCKET
          s, long cmd, u_long FAR * argp,
          int FAR * lpErrno );

          
          s          A descriptor identifying a socket.
          
          cmd       The command to perform on the socket s.
          
          argp      A pointer to a parameter for cmd.
          
          lpErrno   A pointer to the error code.

Remarks   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 the protocol and communications subsystem. The
          following commands are supported:

          Command   Semantics
          
          FIONBIO   Enable or disable non-blocking mode on
                    the socket s.  argp points at an
                    unsigned long, 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.
          
                    The PSCallbackSelect() routine
                    automatically sets a socket to
                    nonblocking mode.  If PSCallbackSelect()
                    has been issued on a socket, then any
                    attempt to use PSioctlsocket() 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 PSCallbackSelect() by
                    calling PSCallbackSelect() with the
                    lEvent parameter equal to 0.
          
          FIONREAD  Determine the amount of data which can
                    be read atomically from socket s. argp
                    points at an unsigned long in which
                    WSPIoctlSocketWSPioctlsocket() stores
                    the result. If s is stream-oriented
                    (e.g., type SOCK_STREAM), FIONREAD
                    returns the total amount of data which
                    may be read in a single
                    WSPRecvWSPrecv(); this is normally the
                    same as the total amount of data queued
                    on the socket. If s is message-oriented
                    (e.g., type SOCK_DGRAM), FIONREAD
                    returns the size of the first datagram
                    (message) queued on the socket.
          
          SIOCATMARK     Determine whether or not all out-of-
                    band data has been read. This applies
                    only to a socket of stream style (e.g.,
                    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 read,
                    the operation returns TRUE. Otherwise it
                    returns FALSE, and the next
                    WSPRecvWSPrecv() or
                    WSPRecvFromWSPrecvfrom() 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 received in order.
                    (Note that a WSPRecvWSPrecv() or
                    WSPRecvFromWSPrecvfrom() will never mix
                    out-of-band and normal data in the same
                    call.) argp points at a BOOL in which
                    WSPIoctlSocketWSPioctlsocket() stores
                    the result.

Compatibility  This function is a subset of ioctl() 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.
{where should we break the news about not allowing any new
          ioctls to be introduced? }
{Not here. This is more of a charter/requirements issue for
          the API extension group.}

Return Value   Upon successful completion, the
          WSPIoctlSocketWSPioctlsocket() returns 0.
          Otherwise, a value of SOCKET_ERROR is returned,
          and a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           cmd is not a valid command, or
                              argp is not an acceptable
                              parameter for cmd, or the
                              command is not applicable to
                              the type of socket supplied
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTSOCK         The descriptor s is not a
                              socket.
          

See Also  WSPPSsocket(), WSPSetSockOptWSPsetsockopt(),
          WSPGetSockOptWSPgetsockopt().
3.1.7 WSPListenWSPlisten()

Description    Establish a socket to listen for incoming
          connection.

          #include <ws2spi.h>

          int WSPAPI WSPListenWSPlisten ( SOCKET s, int
          backlog, int FAR * lpErrno );
          
          s          A descriptor identifying a bound,
                    unconnected socket.
          
          backlog   The maximum length to which the queue of
                    pending connections may grow.
          
          lpErrno   A pointer to the error code.

Remarks   To accept connections, a socket is first created
          with WSPsocket(), a backlog for incoming
          connections is specified with
          WSPListenWSPlisten(), and then the connections are
          accepted with WSPAccept. WSPListenWSPlisten()
          applies only to sockets that are connection-
          oriented (, e.g., those of type SOCK_STREAM). The
          socket s is put into "passive'' mode where
          incoming connections are acknowledged and queued
          pending acceptance by the process.

          This function is typically used by servers that
          could have more than one connection request at a
          time: if a connection request arrives with the
          queue full, the client will receive an error with
          an indication of WSAECONNREFUSED.

          PSlisten() 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 PSlisten() or
          PSaccept() will re-fill the queue to the current
          or most recent "backlog'', if possible, and resume
          listening for incoming connections.
          
Compatibility  backlog is currently limited (silently) to
          SOMAXCONN, which is defined to be 5 in the header
          file. As in 4.3BSD, illegal values (less than 1 or
          greater than 5) are replaced by the nearest legal
          value.
          {Why do we still enforce this? NT limits the
          backlog to 100, not 5, because BIG servers (like
          ftp.microsoft.com) often receive periodic floods
          of connection requests, easily overrunning a
          backlog of 5 connections.}

Return Value   If no error occurs, WSPListenWSPlisten()
          returns 0. Otherwise, a value of SOCKET_ERROR is
          returned, and a specific error code is available
          in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       An attempt has been made to
                              WSPListenWSPlisten() on an
                              address in use.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEINVAL           The socket has not been bound
                              with WSPBindWSPbind().
          
          WSAEISCONN          The socket is already
                              connected.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENOBUFS          No buffer space is available.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       The referenced socket is not
                              of a type that supports the
                              WSPListenWSPlisten()
                              operation.

See Also  WSPAccept, WSPConnect(), WSPsocket().
3.1.8 WSPSelectWSPselect32()

Description    Determine the status of one or more sockets.

          #include <ws2spi.h>

          int WSPAPI WSPSelectWSPselect32 ( int nfds, fd_set
          FAR * readfds, fd_set FAR * writefds,  fd_set FAR
          * exceptfds, const struct timeval FAR * timeout,
          int FAR * lpErrno );

          
          nfds      This argument is ignored and included
                    only for the sake of compatibility.
          
          readfds   An optional pointer to a set of sockets
                    to be checked for readability.
          
          writefds  An optional pointer to a set of sockets
                    to be checked for writability
          
          exceptfds An optional pointer to a set of sockets
                    to be checked for errors.
          
          timeout   The maximum time for PSselect() to wait,
                    or NULL for blocking operation.This
                    value istTThis value should be ignored.
                    (The Winsock DLL will always supply a
                    value of zero for the sake of
                    compatability.)The maximum time for
                    WSPSelect() to wait, or NULL for a
                    blocking operation. Note that the 16-bit
                    Winsock DLL will always pass in a
                    timeout of zero to perform a non-
                    blocking poll on the socket set(s). The
                    32-bit Winsock DLL may pass in any
                    timeout value.
          
          lpErrno   A pointer to the error code.

Remarks   This function is only applicable to the 32 bit
          SPI. The 16 bit Winsock2.DLL uses the
          WSPCallbackSelect() function to implement the API
          version of select() since blocking may be
          requested. WSPSelect32() 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. All entries in an fd_set
          correspond to sockets created by the service
          provider. Upon return, the structure is updated to
          reflect the subset of these sockets which meet the
          specified condition, and WSPSelectWSPselect32()
          returns the total 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.
          
          The parameter readfds identifies those sockets
          which are to be checked for readability. If the
          socket is currently WSPListenWSPlisten()ing, it
          will be marked as readable if an incoming
          connection request has been received, so that an
          WSPAccept is guaranteed to complete immediately.
          For other sockets, readability means that queued
          data is available for reading or, for connection-
          oriented sockets, that the virtual circuit
          corresponding to the socket has been closed, so
          that a WSPRecvWSPrecv() or
          WSPRecvFromWSPrecvfrom() is guaranteed to complete
          immediately. If the virtual circuit was closed
          gracefully, then a WSPRecvWSPrecv() will return
          immediately with 0 bytes read; if the virtual
          circuit was reset, then a WSPRecvWSPrecv() will
          complete immediately with the error code
          WSAECONNRESET. The presence of out-of-band data
          will be checked if the socket option SO_OOBINLINE
          has been enabled (see
          WSPSetSockOptWSPsetsockopt()).
          
          The parameter writefds identifies those sockets
          which are to be checked for writability. If a
          socket is WSPConnect()ing, writability means that
          the connection establishment successfully
          completed. If the socket is not in the process of
          WSPConnect()ing, writability means that a
          WSPSendWSPsend() or WSPSendToWSPsendto() or
          WSAGetBuffer() will complete immediately. [It is
          not specified how long this guarantee can be
          assumed to be valid, particularly in a
          multithreaded environment.]
          
          The parameter exceptfds 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 connection-oriented socket, 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. If a socket is WSPConnect()ing,
          failure of the connect attempt is indicated in
          exceptfds.
          
          Any of readfds, writefds, or exceptfds may be
          given as NULL if no descriptors are of interest.
          
          Four macros are defined in the header file
          ws2spi.h for manipulating the descriptor sets. The
          variable FD_SETSIZE determines 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 ws2spi.h.) 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:
          
          FD_CLR(s, *set)          Removes the descriptor s
                    from set.
          
          FD_ISSET(s, *set)   Nonzero if s is a member of
                    the set, zero otherwise.
          
          FD_SET(s, *set)          Adds descriptor s to set.
          
          FD_ZERO(*set)       Initializes the set to the
                    NULL set.
          
          The parameter timeout controls how long the
          PSselect() may take to complete.  If timeout is a
          null pointer, PSselect() will block indefinitely
          until at least one descriptor meets the specified
          criteria.  Otherwise, timeout points to a struct
          timeval which specifies the maximum time that
          PSselect() should wait before returning.  If the
          timeval is initialized to {0, 0}, PSselect() will
          return immediately; this is used to "poll" the
          state of the selected sockets.  If this is the
          case, then the PSselect() call is considered
          nonblocking and the standard assumptions for
          nonblocking calls apply.  For example, the
          blocking hook must not be called, and the PII
          implementation must not yield.

Return Value   WSPPSSelectselect32() returns the total
          number of descriptors which are ready and
          contained in the fd_set structures, 0 if the time
          limit expired, or SOCKET_ERROR if an error
          occurred. If the return value is SOCKET_ERROR, a
          specific error code is available in lpErrno.

Comments  WSPPSSelect 32() has no effect on the
          persistencepersistance of socket events registered
          with WSPEventSelect().

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this API.
          
          WSAEFAULT           The Winsock service provider
                              was unable to allocated needed
                              resources for its internal
                              operations, or the readfds,
                              writefds, or exceptfds
                              parameters are not part of the
                              user address space.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           The timeout value is not
                              valid.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              WSACancelBlockingCall().
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTSOCK         One of the descriptor sets
                              contains an entry which is not
                              a socket.

See Also  WSPAccept(), WSPConnect(), WSPRecvWSPrecv(),
          WSPRecvFromWSPrecvfrom(), WSPSendWSPsend(),
          WSPSendToWSPsendto(), WSPEventSelect()
3.1.9 WSPSetSockOptWSPsetsockopt()

Description    Set a socket option.

          #include <ws2spi.h>

          int WSPAPI WSPSetSockOptWSPsetsockopt ( SOCKET s,
          int level, int optname,
          const char FAR * optval, int optlen, int FAR *
          lpErrno );

          
          s          A descriptor identifying a socket.
          
          level     The level at which the option is
                    defined; the only supported levels are
                    SOL_SOCKET and SOL_PROVIDER.
                    (SOL_PROVIDER is defined to be an alias
                    for IPPROTO_TCP for the sake of
                    compatibility with Windows Sockets
                    specification 1.1.)
          
          optname   The socket option for which the value is
                    to be set.
          
          optval    A pointer to the buffer in which the
                    value for the requested option is
                    supplied.
          
          optlen    The size of the optval buffer.
          
          lpErrno   A pointer to the error code.

Remarks   WSPSetSockOptWSPPSsetsockopt() 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, they are always
          present at the uppermost "socket'' level. 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.

          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,
          optval points to a nonzero integer. To disable the
          option optval points to an integer equal to zero.
          optlen should be equal to sizeof(int) for Boolean
          options. For other options, optval points to the
          an integer or structure that contains the desired
          value for the option, and optlen is the length of
          the integer or structure.
          
          
 level = SOL_SOCKET                      
 Value                          Type     Meaning
 SO_BROADCAST                   BOOL     Allow transmission of
                                         broadcast messages on the
                                         socket.
 SO_DEBUG                       BOOL     Record debugging
                                         information.
 SO_DONTLINGER                  BOOL     Don't block close waiting
                                         for unsent data to be
                                         sent. Setting this option
                                         is equivalent to setting
                                         SO_LINGER with l_onoff set
                                         to zero.
 SO_DONTROUTE                   BOOL     Don't route: send directly
                                         to interface.
 SO_GROUP_PRIORITY              int      Specify the relative
                                         priority to be established
                                         for sockets that are part
                                         of a socket group.
 SO_KEEPALIVE                   BOOL     Send keepalives
 SO_LINGER                      struct   Linger on close if unsent
                                linger   data is present
 SO_OOBINLINE                   BOOL     Receive out-of-band data
                                         in the normal data stream.
 SO_RCVBUF                      int      Specify buffer size for
                                         receives
 SO_REUSEADDR                   BOOL     Allow the socket to be
                                         bound to an address which
                                         is already in use. (See
                                         bind().)
 SO_SNDBUF                      int      Specify buffer size for
                                         sends.
                                         
 level = SOL_PROVIDER                    
 (aliased to IPPROTO_TCP)
 PVD_CONFIG                     Service  This object stores the
                                Provide  configuration information
                                r        for the service provider
                                Depende  associated with socket s.
                                nt       The exact format of this
                                         data structure is service
                                         provider specific.
 TCP_NODELAY                    BOOL     Disables the Nagle
                                         algorithm for send
                                         coalescing.
               
               BSD options not supported for
               WSPSetSockOptWSPsetsockopt() are:
               
Value                       Type     Meaning
SO_ACCEPTCONN               BOOL     Socket is listening
SO_ERROR                    int      Get error status and clear
SO_RCVLOWAT                 int      Receive low water mark
SO_RCVTIMEO                 int      Receive timeout
SO_SNDLOWAT                 int      Send low water mark
SO_SNDTIMEO                 int      Send timeout
SO_TYPE                     int      Type of the socket
IP_OPTIONS                           Set options field in IP
                                     header.
          
     SO_DEBUG
          Winsock service providers 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
          specification.
          
     SO_GROUP_PRIORITY
          Group priority indicates the relative priority of
          the specified socket relative to other sockets
          within the socket group. Values are non-negative
          integers, with zero corresponding to the highest
          priority. Priority values represent a hint to the
          underlying service provider about how potentially
          scarce resources should be allocated. For example,
          whenever two or more sockets are both ready to
          transmit data, the highest priority socket (lowest
          value for SO_GROUP_PRIORITY) should be serviced
          first, with the remainder serviced in turn
          according to their relative priorities.
          
          
          
          Eligibility for grouping sockets together is based
          on the destination address of sockets marked with
          the group option.  Sockets which share destination
          addresses that are identical except for the last
          component of the address (e.g. the port number in
          the IP address family) are eligible for group
          multiplexing.  The manner in which multiplexing is
          implemented is left up to the service provider.The
          WSAENOPROTOOPT error is indicated for non group
          sockets or for service providers which do not
          support group sockets.
          
     SO_KEEPALIVE
          An application may request that a TCP/IP provider
          enable the use of "keep-alive" packets on TCP
          connections by turning on the SO_KEEPALIVE socket
          option. A Winsock provider 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:
          Requirements for Internet Hosts -- Communication
          Layers. 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.
          
     SO_LINGER
          SO_LINGER controls the action taken when unsent
          data is queued on a socket and a
          WSPCloseSocketWSPclosesocket() is performed. See
          WSPCloseSocketWSPclosesocket() for a description
          of the way in which the SO_LINGER settings affect
          the semantics of WSPCloseSocketWSPclosesocket().
          The application sets the desired behavior by
          creating a struct linger (pointed to by the optval
          argument) with the following elements:
          
          struct linger {
               int  l_onoff;
               int  l_linger;
          }
          
          
          To enable SO_LINGER, the application should set
          l_onoff to a non-zero value, set l_linger to 0 or
          the desired timeout (in seconds), and call
          WSPSetSockOptWSPsetsockopt(). To enable
          SO_DONTLINGER (i.e. disable SO_LINGER) l_onoff
          should be set to zero and
          WSPSetSockOptWSPsetsockopt() should be called.
          
     SO_RESERVED_BW and SO_AVAILABLE_BW
          These options are used primarily with isochronous
          sockets, although both options have meaningful
          interpretations for non-isochronous sockets as
          well.  When dealing with isochronous sockets, the
          application may retrieve the value of
          SO_AVAILABLE_BW to determine the maximum amount of
          bandwidth that is available to be reserved.  It
          uses SO_RESERVED_BW to actually request bandwidth
          allocation or to determine the current bandwidth
          already allocated to the socket.  In both
          instances, bandwidth values are expressed in "bits
          per second (bps)".
          
          For non-isochronous sockets, the value of
          SO_AVAILABLE_BW is used to provide a hint as to
          the relative capacity of the underlying network.
          Applications may wish to know, for example,
          whether they are running over a 1200 baud serial
          line or a 155 Mbps ATM link. Since in many
          instances it is impossible for a non-isochronous
          service provider to supply a precise value for
          this option, applications must realize that the
          supplied value may represent nothing more than a
          reasonable approximation of the capacity of the
          underlying network.  Applications may likewise use
          the value of SO_RESERVED_BW to provide a hint to
          the service provider about the desired amount of
          bandwidth.
          
     SO_REUSEADDR
          By default, a socket may not be bound (see
          WSPBindWSPbind()) to a local address which is
          already 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 local address as long as the remote
          addresses are different. To inform the Winsock
          provider that a WSPBindWSPbind() on a socket
          should not be disallowed because the desired
          address is already in use by another socket, the
          application should set the SO_REUSEADDR socket
          option for the socket before issuing the
          WSPBindWSPbind(). Note that the option is
          interpreted only at the time of the
          WSPBindWSPbind(): 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
          WSPBindWSPbind() has no effect on this or any
          other socket.
          
     PVD_CONFIG
          This option specifies an object previously
          obtained using getsockopt().  This object stores
          the configuration information for the service
          provider associated with socket s. The exact
          format of this data structure is service provider
          specific.
          
     TCP_NODELAY
          The TCP_NODELAY option is specific to TCP/IP
          service providers. It is used to disable 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 impede
          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
          performance.
          

Return Value   If no error occurs,
          WSPSetSockOptWSPsetsockopt() returns 0. Otherwise,
          a value of SOCKET_ERROR is returned, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           optval is not in a valid part
                              of the process address space.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEINVAL           level is not valid, or the
                              information in optval is not
                              valid.
          
          WSAENETRESET        Connection has timed out when
                              SO_KEEPALIVE is set.
          
          WSAENOPROTOOPT      The option is unknown or
                              unsupported for the specified
                              provider.
          
          WSAENOTCONN         Connection has been reset when
                              SO_KEEPALIVE is set.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

See Also  WSPBindWSPPSbind(), WSPGetSockOptWSPgetsockopt(),
          WSPIoctlSocketWSPioctlsocket(), WSPsocket(),
          WSPEventSelect().
3.1.10 WSPShutdownWSPshutdown()

Description    Disable sends and/or receives on a socket.

          #include <ws2spi.h>

          int WSPAPI WSPShutdownWSPshutdown ( SOCKET s, int
          how, int FAR * lpErrno );

          
          s          A descriptor identifying a socket.
          
          how       A flag that describes what types of
                    operation will no longer be allowed.
          
          lpErrno   A pointer to the error code.

Remarks   WSPShutdownWSPPSshutdown() is used on all types of
          sockets to disable reception, transmission, or
          both.

          If how is SD_RECEIVE, 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, incoming datagrams are
          accepted and queued. In no case will an ICMP error
          packet be generated.
          
          If how is SD_SEND, subsequent sends on the socket
          are disallowed. For TCP sockets, a FIN will be
          sent.
          
          Setting how to SD_BOTH disables both sends and
          receives as described above.

          Note that WSPShutdownWSPshutdown() does not close
          the socket, and resources attached to the socket
          will not be freed until
          WSPCloseSocketWSPclosesocket() is invoked.
          
Comments  WSPShutdownWSPPSshutdown() does not block
          regardless of the SO_LINGER setting on the socket.
          An application should not rely on being able to re-
          use a socket after it has been shut down. In
          particular, a Winsock service provider is not
          required to support the use of WSPConnect() on
          such a socket.

Return Value   If no error occurs, WSPShutdownWSPshutdown()
          returns 0. Otherwise, a value of SOCKET_ERROR is
          returned, and a specific error code is available
          in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           how is not valid, or is not
                              consistent with the socket
                              type, e.g., SD_SEND is used
                              with a UNI_RECV socket type.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAENOTCONN         The socket is not connected
                              (connection-oriented sockets
                              only).
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

See Also  WSPConnect(), WSPsocket().
3.1.15 WSPsocket()
Description    Create a socket.

          #include <ws2spi.h>

          SOCKET PASCAL FAR WSPsocket ( int af, int type,
          int protocol, LPSTR lpszProviderKey, int FAR *
          lpErrno );

          
          af        An address family specification.  The
                    only format currently supported is
                    PF_INET, which is the ARPA Internet
                    address format.
          
          type      A type specification for the new socket.
          
          protocol  A particular protocol to be used with
                    the socket, or 0 if the caller does not
                    wish to specify a protocol.
          
          lpszProviderKey     A NULL-terminated string
                    identifying the Winsock service provider
                    to use. This information is useful to
                    provider implementations that present
                    multiple service provider appearances to
                    Winsock.
          
          lpErrno   A pointer to the error code.

Remarks   PSsocket() causes a socket descriptor and any
          related resources to be allocated and bound to a
          specific transport service provider.  If a
          protocol is not specified (i.e., equal to 0), the
          default for the specified socket type is used.
          However, the address family may be given as
          AF_UNSPEC (unspecified), in which case the
          protocol parameter must be specified.  The
          protocol number to use is particular to the
          "communication domain'' in which communication is
          to take place.  lpszProviderKey uniquely
          identifies the required transport service
          provider.
          
          All the socket created are in non-blocking mode.
          
          The following type specifications may be supported
          (all sockets are bi-directional unless specified
          otherwise):
          
           Type                    Explanation
           SOCK_STREAM             Alias for
                                    SOCK_REL_STREAM.
           
           SOCK_DGRAM              Alias for
                                    SOCK_UNREL_DGRAM.
           
           SOCK_SEQPACKET          Alias for
                                    SOCK_REL_DSTREAM.
           
           SOCK_RAW                Raw socket.
           
           SOCK_REL_STREAM         Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, byte
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.  Uses TCP
                                    for the Internet
                                    address family.
           
           SOCK_REL_DSTREAM        Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, message
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.
           
           SOCK_UNREL_DSTREAM      Connection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, message
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.
           
           SOCK_REL_UNISEND_DSTREAMConnection-oriented,
                                    reliable, one-way (send
                                    only), unduplicated,
                                    sequenced, message
                                    stream. The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_REL_UNIRECV_DSTREA
                                    M.
           
           SOCK_REL_UNIRECV_DSTREAMConnection-oriented,
                                    reliable, one-way
                                    (receive only),
                                    unduplicated,
                                    sequenced, message
                                    stream.  The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_REL_UNISEND_DSTREA
                                    M.
           
           SOCK_UNREL_UNISEND_DSTREAM   Connection-
                                    oriented, unreliable,
                                    one-way (send only),
                                    unduplicated,
                                    sequenced, message
                                    stream. The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_UNREL_UNIRECV_DSTR
                                    EAM.
           
           SOCK_UNREL_UNIRECV_DSTREAM   Connection-
                                    oriented, unreliable,
                                    one-way (receive only),
                                    unduplicated,
                                    sequenced, message
                                    stream.  The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_UNREL_UNISEND_DSTR
                                    EAM.
           
           SOCK_REL_DGRAM          Connectionless,
                                    reliable, datagram.
           
           SOCK_UNREL_DGRAM        Connectionless,
                                    unreliable, datagram.
           
           SOCK_REL_ISOCH_DSTREAM  Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, isochronous,
                                    message streamwith an
                                    out-of-band data
                                    transmission mechanism.
           
           SOCK_UNREL_ISOCH_DSTREAMConnection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, isochronous,
                                    message streamwith an
                                    out-of-band data
                                    transmission mechanism.
           
           SOCK_UNREL_ISOCH_STREAM Connection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, isochronous,
                                    byte streamwith an out-
                                    of-band data
                                    transmission mechanism.
              
          
          Connection-oriented sockets such as
          SOCK_REL_STREAM provide full-duplex connections,
          and must be in a connected state before any data
          may be sent or received on them.  A connection to
          another socket is created with a WSPConnect()
          call.  Once connected, data may be transferred
          using WSPsend() and WSPrecv() calls.  When a
          session has been completed, a WSPclosesocket()
          must be performed.  Out-of-band data may also be
          transmitted as described in send() and received as
          described in recv().
          
          
          The communications protocols used to implement a
          reliable, connection-oriented socket 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
          error code set to WSAETIMEDOUT.
          
          Connectionless, message-oriented sockets allow
          sending and receiving of datagrams to and from
          arbitrary peers using WSPsendto() and
          WSPrecvfrom().  If such a socket is WSPConnect()ed
          to a specific peer, datagrams may be send to that
          peer using WSPsend() and may be received from
          (only) this peer using WSPrecv().


Return Value   If no error occurs, WSPsocket() returns a
          descriptor referencing the new socket.  Otherwise,
          a value of INVALID_SOCKET is returned, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEAFNOSUPPORT     The specified address family
                              is not supported.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be created.
          
          WSAEPROTONOSUPPORT  The specified protocol is not
                              supported.
          
          WSAEPROTOTYPE       The specified protocol is the
                              wrong type for this socket.
          
          WSAESOCKTNOSUPPORT  The specified socket type is
                              not supported in this address
                              family.

See Also  WSPAccept, WSPbind(), WSPConnect(),
          WSPgetsockname(), WSPgetsockopt(),
          WSPsetsockopt(), WSPlisten(), WSPrecv(),
          WSPrecvfrom(), PSselect(), WSPsend(), WSPsendto(),
          WSPshutdown(), WSPioctlsocket().

 3.21.111 WSPAccept()

Description    Conditionally accept a connection based on
          the return value of a condition function, and
          optionally create and/or join a socket group.

          #include <ws2spi.h>

          SOCKET WSPAPI WSPAccept ( SOCKET s, struct
          sockaddr FAR * addr, int FAR * addrlen,
          LPCONDITIONPROC lpfnCondition, DWORD
          dwCallbackData,
          int FAR * lpAcceptAction,int FAR * lpErrno );

          
          s          A descriptor identifying a socket which
                    is listening for connections after a
                    WSPListenWSPlisten().
          
          addr      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 addr
                    argument is determined by the address
                    family established when the socket was
                    created.
          
          addrlen   An optional pointer to an integer which
                    contains the length of the address addr.
          
          lpfnCondition  The address of the optional, the
                    Winsock DLL-supplied condition function
                    which will make an accept/reject
                    decision based on the caller information
                    passed in as parameters, and optionally
                    create and/or join a socket group by
                    assigning appropriate value to the
                    result parameter g of this function.
          
          dwCallbackData The callback data passed back to
                    the Winsock DLL in the condition
                    function. This object is not interpreted
                    by the service providerWinsock
                    implementation.
          
          lpAcceptAction A optional pointer to the action
                    taken by the condition function.
          
          lpErrno   A pointer to the error code.

Remarks   This routine extracts the first connection on the
          queue of pending connections on s, and checks it
          against the condition function, provided the
          condition function is specified (i.e., not NULL).
          If lpfnCondition is set to NULL, a connection is
          accepted unconditionally, and no socket group is
          created or joined. If the condition function
          returns CF_ACCEPT, this routine creates a new
          socket with the same properties as s and returns a
          handle to the new socket, and then optionally
          creates and/or joins a socket group based on the
          value of the result parameter g in the condition
          function. If the condition function returns
          CF_REJECT, this routine rejects this connection
          request. The condition function runs in the same
          thread as this routine does, and should return as
          soon as possible. If the decision cannot be made
          immediately, the condition function willshould
          return CF_DEFER to indicate that no decision has
          been made, and no action about this connection
          request should be taken by the service provider.
          When the Winsock DLL is ready to take action on
          the connection request, it may invoke WSPAccept()
          again and return either CF_ACCEPT or CF_REJECT as
          a return value from the condition function.
          
          If no pending connections are present on the
          queue, and the socket is not marked as non-
          blocking, PSAcceptEx() blocks the caller until a
          connection is present.  If the socket is marked
          non-blocking and no pending connections are
          present on the queue, WSPAccept() returns an error
          as described below. The accepted socket may not be
          used to accept more connections. The original
          socket remains open.
          
          The argument addr is a result parameter that is
          filled in with the address of the connecting
          entity, as known to the communications layer. The
          exact format of the addr parameter is determined
          by the address family in which the communication
          is occurring. The addrlen is a value-result
          parameter; it should initially contain the amount
          of space pointed to by addr; on return it will
          contain the actual length (in bytes) of the
          address returned. This call is used with
          connection-oriented socket types such as
          SOCK_STREAM. If addr and/or addrlen are equal to
          NULL, then no information about the remote address
          of the accepted socket is returned. Otherwise,
          these two parameters will be filled in regardless
          of whether the condition function is specified or
          what it returns.

          The prototype of the condition function is as
          follows:
          
               int WSACALLBACK ConditionFunc( SOCKET s,
          LPWSABUF lpCallerId, LPWSABUF lpCallerData,
          LPWSABUF lpCalleeId, LPWSABUF lpCalleeData, GROUP
          FAR * g, DWORD dwCallbackData );
          
          LPWSABUF is defined in ws2spi.h as follows:
          
               typedef struct _WSABUF {
                    int       len;      // the length of the
          buffer
                    char FAR *     buf; // the pointer to
          the buffer
               } WSABUF, FAR * LPWSABUF;
          
          ConditionFunc is a placeholder for athe Winsock
          DLL supplied function pointername. The actual
          condition function must reside in a DLL or
          application module and be exported in the module
          definition file.  You must use MakeProcInstance()
          to get a procedure-instance address for the
          callback function.It is invoked in the same thread
          as WSPAccept(), thus no other Winsock functions
          can be called. The s parameter is the socket
          descriptor of the listening socket specified in
          PSAcceptEx().  The lpCallerId and lpCallerData are
          value parameters which contain the address of the
          connecting entity and any user data that was sent
          along with the connection request, respectively.
          The lpCalleeId is a value parameter which contains
          the local address of the connected entity. The
          lpCalleeData is a result parameter in which the
          condition function fills in the user data passed
          back to the connecting entity. lpCalleeData->len
          initially contains the length of the buffer
          allocated by the service provider, and 0 means
          user data back to the caller is not supported. If
          lpCalleeData->len is set to 0, no user data will
          be passed back. The exact format of the address
          and user data is specific to the address family to
          which the socket belongs.
          
          The result parameter g is assigned within the
          condition function to indicate the following
          actions:
               if g is an existing socket group id, add s to
          this group, provided all the
          requirements set by this group are met; or
               if g = SG_UNCONSTRAINED_GROUP, create an
          unconstrained socket               group and have
          s as the first member; or
               if g = SG_CONSTRAINED_GROUP, create a
          constrained socket group and            have s as
          the first member; or
               if g = NULL, no operation is performed.
          For unconstrained groups, any set of sockets may
          be grouped together as long as they are supported
          by a single Winsock service provider and are
          connection-oriented. A constrained socket group
          requires that connections on all grouped sockets
          be to the same host. For newly created socket
          groups, the new group id can be retrieved by
          lpGroupAction or using
          WSPGetSockOptWSPgetsockopt() with option
          SO_GROUP_ID, if this operation completes
          successfully.
          
          The lpAcceptAction is a result parameter which
          contains the action taken by the condition
          function, i.e., CF_ACCEPT, CF_REJECT, or CF_DEFER,
          if this function returns successfully.  If
          lpAcceptAction is set to NULL before calling this
          function, no information will be passed back.
          
Return Value   If no error occurs, WSPAccept() returns a
          value of type SOCKET which is a descriptor for the
          accepted socket. Otherwise, a value of
          INVALID_SOCKET is returned, and a specific error
          code is available in lpErrno.

          The integer referred to by addrlen initially
          contains the amount of space pointed to by addr.
          On return it will contain the actual length in
          bytes of the address returned.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this API.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAECONNREFUSED     The connection request was
                              forcefully rejected as
                              indicated in the return value
                              of the condition function
                              (CF_REJECT).
          
          WSAEFAULT           The addrlen argument is too
                              small (less than the sizeof a
                              struct sockaddr) or the
                              lpfnCondition is not part of
                              the user address space.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEINVAL           WSPListenWSPlisten() was not
                              invoked prior to WSPAccept(),
                              parameter g specified in the
                              condition function is not a
                              valid value, the return value
                              of the condition function is
                              not a valid one, or any case
                              where the specified socket is
                              in an invalid state.
          
          WSAEMFILE           The queue is non-empty upon
                              entry to WSPAccept() and there
                              are no socket descriptors
                              available.
          
          WSAENOBUFS          No buffer space is available.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       The referenced socket is not a
                              type that supports connection-
                              oriented service.
          
          WSATRY_AGAIN        The acceptance of the
                              connection request was
                              deferred as indicated in the
                              return value of the condition
                              function (CF_DEFER).
          
          WSAEWOULDBLOCK      No connections are present to
                              be accepted, or the connection
                              request that was deferred has
                              timed out or been withdrawn.
          
See Also  WSPAccept(), WSPBindWSPbind(), WSPConnect(),
          WSPGetSockOptWSPgetsockopt(),
          WSPListenWSPlisten(), WSPSelectWSPselect(),
          WSPsocket(), WSPEventSelect().
3.1.2.12 WSPAsyncSelect32()

Description    Request event notification for a socket.
{For obvious reasons, this function description is
particularly bad about sounding like an API function
description instead of an SPI function description }

          #include <ws2spi.h>

          int WSPAPI WSPAsyncSelect32 ( SOCKET s, HWND hWnd,
          unsigned int wMsg, long lEvent, int FAR * lpErrno
          );

          
          s          A descriptor identifying the socket for
                    which event notification is required.
          
          hWnd      A handle identifying the window which
                    should receive a message when a network
                    event occurs.
          
          wMsg      The message to be received when a
                    network event occurs.
          
          lEvent    A bitmask which specifies a combination
                    of network events in which the
                    application is interested.
          
          lpErrno   A pointer to the error code.

Remarks   This function is only applicable to available in
          the 32-bit SPI. The 16 bit Winsock2.DLL uses
          WSPCallbackSelect() to implement the API function
          WSAAsyncSelect().

          This function is used to request that the service
          provider should send a message to the window hWnd
          whenever it detects any of the network events
          specified by the lEvent parameter. The message
          which should be sent is specified by the wMsg
          parameter. The socket for which notification is
          required is identified by s.
          
          This function automatically sets socket s to non-
          blocking mode, regardless of the value of lEvent.
          See WSPIoctlSocketWSPioctlsocket() about how to
          set the socket back to blocking mode.
          
          The lEvent parameter is constructed by or'ing any
          of the values specified in the following list.

               Value      Meaning
               FD_READ    Want to receive notification of
                          readiness for reading
               FD_WRITE   Want to receive notification of
                          readiness for writing
               FD_OOB     Want to receive notification of
                          the arrival of out-of-band data
               FD_ACCEPT  Want to receive notification of
                          incoming connections
               FD_CONNECT Want to receive notification of
                          completed connection
               FD_CLOSE   Want to receive notification of
                          socket closure
               FD_QOS     Want to receive notification of
                          socket Quality of Service (QOS)
                          changes
               FD_GROUP_QOS    Want to receive notification
                          of socket group Quality of
                          Service (QOS) changes
               

          Issuing a WSPAsyncSelect32() for a socket cancels
          any previous WSPAsyncSelect32() for the same
          socket. For example, to receive notification for
          both reading and writing, the Winsock DLL will
          application must call WSPAsyncSelect32() with both
          FD_READ and FD_WRITE, as follows:
          
          rc = WSPAsyncSelect32(s, hWnd, wMsg,
                    FD_READ|FD_WRITE, &error);
          
          It is not possible to specify different messages
          for different events. The following code will not
          work; the second call will cancel the effects of
          the first, and only FD_WRITE events will be
          reported with message wMsg2:
          
          rc = WSPAsyncSelect32WSAPsyncSelect(s, hWnd,
                    wMsg1, FD_READ, &error);
          rc = WSPAsyncSelect32WSAPsyncSelect(s, hWnd,
                    wMsg2, FD_WRITE, &error);
          
          To cancel all notification - i.e., to indicate
          that the service provider Winsock2 should send no
          further messages related to network events on the
          socket - lEvent should be set to zero.
          
          rc = WSPAsyncSelect32WSAPsyncSelect(s, hWnd, 0, 0,
                    &error);
          
          Although in this instance WSPAsyncSelect32()
          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 socket with WSPCloseSocketclosesocket()
          also cancels WSPAsyncSelect32() message sending,
          but the same caveat about messages in the queue
          prior to the WSPCloseSocketWSPclosesocket() still
          applies.
          
          Since a WSPAcceptWSPaccept()'ed socket has the
          same properties as the listening socket used to
          accept it, any WSPAsyncSelect32() events set for
          the listening socket apply to the accepted socket.
          For example, if a listening socket has
          WSPAsyncSelect32() events FD_ACCEPT, FD_READ, and
          FD_WRITE, then any socket accepted on that
          listening socket will also have FD_ACCEPT,
          FD_READ, and FD_WRITE events with the same wMsg
          value used for messages. If a different wMsg or
          events are desired, the application should call
          WSPAsyncSelect32(), passing the accepted socket
          and the desired new information.1
          
          When one of the nominated network events occurs on
          the specified socket s, the application's window
          hWnd receives message wMsg. The wParam argument
          identifies the socket on which a network event has
          occurred. The low word of lParam specifies the
          network event that has occurred. The high word of
          lParam contains any error code. The error code be
          any error as defined in Winsock2.h.
          
          The error and event codes may be extracted from
          the lParam using the macros WSAGETSELECTERROR and
          WSAGETSELECTEVENT, defined in Winsock2.h as:
          
          #define WSAGETSELECTERROR(lParam)
                    HIWORD(lParam)
          #define WSAGETSELECTEVENT(lParam)
                    LOWORD(lParam)
          
          The use of these macros will maximize the
          portability of the source code for the
          application.
          
          The possible network event codes which may be
          returned are as follows:
          
               Value      Meaning
               FD_READ    Socket s ready for reading
               FD_WRITE   Socket s ready for writing
               FD_OOB     Out-of-band data ready for
                          reading on socket s.
               FD_ACCEPT  Socket s ready for accepting a
                          new incoming connection
               FD_CONNECT Connection initiated on socket s
                          completed
               FD_CLOSE   Connection identified by socket s
                          has been closed
               FD_QOS     Quality of Service associated
                          with socket s has changed.
               FD_GROUP_QOS    Quality of Service
                          associated with the socket group
                          to which s belongs has changed.
               
          
Return Value   The return value is 0 if the application's
          declaration of interest in the network event set
          was successful. Otherwise the value SOCKET_ERROR
          is returned, and a specific error code is
          available in lpErrno.

Comments  Although WSPAsyncSelect32() can be called with
          interest in multiple events, the application
          window will receive a single message for each
          network event.
          
          As in the case of the WSPSelectWSPselect()
          function, WSPAsyncSelect32() will frequently be
          used to determine when a data transfer operation
          (WSPSendWSPsend() or WSPRecvWSPrecv()) can be
          issued with the expectation of immediate success.
          Nevertheless, a robust application must be
          prepared for the possibility that it may receive a
          message and issue a Winsock2 call which returns
          WSAEWOULDBLOCK immediately. For example, the
          following sequence of events is possible:
          
          (i)       data arrives on socket s; Winsock2 posts
                    WSPAsyncSelect32() message
          (ii)      application processes some other message
          (iii)     while processing, application issues an
                    WSPIoctlSocketWSPioctlsocket(s,
                    FIONREAD...) and notices that there is
                    data ready to be read
          (iv)      application issues a
                    WSPRecvWSPrecv(s,...) to read the data
          (v)       application loops to process next
                    message, eventually reaching the
                    WSPAsyncSelect32() message indicating
                    that data is ready to read
          (vi)      application issues
                    WSPRecvWSPrecv(s,...), which fails with
                    the error WSAEWOULDBLOCK.
          
          Other sequences are possible.
          
          The WinsockTheWinsock2 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 window, no further message(s) for that
          network event will be posted to the application
          window until the application makes the function
          call which implicitly reenables notification of
          that network event.

          Event          Re-enabling function
          FD_READ        WSPRecvWSPrecv() or
                         WSPRecvFromWSPrecvfrom()
          FD_WRITE       WSPSendWSPsend() or
                         WSPSendToWSPsendto() or
                         WSAGetBuffer()
          FD_OOB         WSPRecvWSPrecv()
          FD_ACCEPT      WSPAcceptWSPaccept() or
                         WSPAcceptEx()  unless the error
                         code returned is WSATRY_AGAIN
                         indicating that the condition
                         function returned CF_DEFER
          FD_CONNECT     NONE
          FD_CLOSE       NONE
          FD_QOS         WSPGetSockOptWSPgetsockopt() with
                         option SO_FLOWSPEC
          FD_GROUP_QOS   WSPGetSockOptWSPgetsockopt() with
                         option SO_GROUP_FLOWSPEC
          
          Any call to the reenabling routine, even one which
          fails, results in reenabling of message posting
          for the relevant event.
          
          For FD_READ, FD_OOB, FD_ACCEPT, FD_QOS and
          FD_GROUP_QOS events, message posting is "level-
          triggered." This means that if the reenabling
          routine is called and the relevant event is still
          valid after the call, a WSPAsyncSelect32() message
          is posted to the application. This allows an
          application to be event-driven and not be
          concerned with the amount of data that arrives at
          any one time. Consider the following sequence:
          
          (i)       network transport stack receives 100
                    bytes of data on socket s and causes
                    Winsock2 to post an FD_READ message.
          (ii)      The application issues WSPRecvWSPrecv(
                    s, buffptr, 50, 0) to read 50 bytes.
          (iii)     another FD_READ message is posted since
                    there is still data to be read.
          
          With these semantics, an application need not read
          all available data in response to an FD_READ
          message--a single WSPRecvWSPrecv() in response to
          each FD_READ message is appropriate. If an
          application issues multiple WSPRecvWSPrecv() calls
          in response to a single FD_READ, it may receive
          multiple FD_READ messages. Such an application may
          wish to disable FD_READ messages before starting
          the WSPRecvWSPrecv() calls by calling
          WSPAsyncSelect32() with the FD_READ event not set.
          
          If an event has already happened when the
          application calls WSPAsyncSelect32() or when the
          reenabling function is called, then a message is
          posted as appropriate. All the events have
          persistence beyond the occurrence of their
          respective events. For example, consider the
          following sequence: 1) an application calls
          WSPListenWSPlisten(), 2) a connect request is
          received but not yet accepted, 3) the application
          calls WSPAsyncSelect32() specifying that it wants
          to receive FD_ACCEPT messages for the socket. Due
          to the persistence of events, Winsock2 posts an
          FD_ACCEPT message immediately.
          
          The FD_WRITE event is handled slightly
          differently. An FD_WRITE message is posted when a
          socket is first connected with
          WSPConnectWSPconnect() or accepted with
          WSPAcceptWSPaccept(), and then after a
          WSPSendWSPsend() or WSPSendToWSPsendto(), or
          WSAGetBuffer() fails with WSAEWOULDBLOCK and
          buffer space becomes available. Therefore, an
          application can assume that sends are possible
          starting from the first FD_WRITE message and
          lasting until a send returns WSAEWOULDBLOCK. After
          such a failure the application will be notified
          that sends are again possible with an FD_WRITE
          message.
          
          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
          register an interest in, and will receive, FD_READ
          events, not FD_OOB events. An application may set
          or inspect the way in which out-of-band data is to
          be handled by using WSPSetSockOptWSPsetsockopt()
          or WSPGetSockOptWSPgetsockopt() for the
          SO_OOBINLINE option.
          
          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 WSAECONNRESET, then
          the socket's virtual circuit was reset. This only
          applies to connection-oriented sockets such as
          SOCK_STREAM.
          
          The FD_CLOSE message 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. This results from the remote end
          performing a WSPShutdownWSPshutdown() on the send
          side or a WSPCloseSocketWSPclosesocket().
          
          Please note your application will receive ONLY an
          FD_CLOSE message to indicate closure of a virtual
          circuit, and only when all the received data has
          been read if this is a graceful close. It will NOT
          receive an FD_READ message to indicate this
          condition.
          
          The FD_QOS or FD_GROUP_QOS message is posted when
          any field in the flow spec associated with socket
          s or the socket group that s belongs to has
          changed, respectively. Applications might use
          WSPGetSockOptWSPgetsocketopt() with option
          SO_FLOWSPEC or SO_GROUP_FLOWSPEC to get the
          current QOS for socket s or for the socket group s
          belongs to, respectively.
          
Error Codes                   WSAENETDOWN    The network
                              subsystem has failed.
          
          WSAEINVAL           Indicates that one of the
                              specified parameters was
                              invalid, or the specified
                              socket is in an invalid state.
          
          WSAEINPROGRESS      A blocking Winsock2 call is in
                              progress, or the service
                              provider is still processing a
                              callback function (see section
                              ???).
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

          Additional error codes may be set when an
          application window receives a message. This error
          code is extracted from the lParam in the reply
          message using the WSAGETSELECTERROR macro.
          Possible error codes for each network event are:
          Event: FD_CONNECT
          Error Code          Meaning
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAECONNREFUSED     The attempt to connect was
                              forcefully rejected.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAETIMEDOUT        Attempt to connect timed out
                              without establishing a
                              connection

          Event: FD_CLOSE
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAECONNRESET       The connection was reset by
                              the remote side.
          
          WSAECONNABORTED     The connection was aborted due
                              to timeout or other failure.
          
          Event: FD_READ
          Event: FD_WRITE
          Event: FD_OOB
          Event: FD_ACCEPT
          Event: FD_QOS
          Event: FD_GROUP_QOS
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          

See Also  WSPSelectWSPselect()
3.1.2.13 WSPCallbackSelect16()

Description    Request event notification for a socket via
          the specified callback function.

          #include <ws2spi.h>

          int WSPAPI WSPCallbackSelect16 ( SOCKET s,
          LPSELECTPROC lpfnCallback,
          DWORD dwCallbackData, long lEvent, int FAR *
          lpErrno );

          s          A descriptor identifying the socket for
                    which event notification is required.
          
          lpfnCallback   The procedure instance address of
                    the callback function to be invoked by
                    Winsock service providers whenever a
                    registered network event happens.
          
          dwCallbackData The callback data which is passed
                    back to the application as a parameter
                    to the callback function. This object is
                    not interpreted by the Winsock service
                    provider.
          
          lEvent    A bitmask which specifies a combination
                    of network events in which the Winsock
                    DLL is interested.
          
          lpErrno   A pointer to the error code.
          

Remarks   This function is only applicable toavailable in
          the 16-bit SPI. The 16 bit Winsock2.DLL uses this
          function to implement the select(),
          WSAAsyncSelectWSAASyncSelect(), and
          WSPEventSelectWSAEventSelect() API functions.
          
          This function will enables the function-based
          callback mechanism for the specified socket. The
          callback function will be invoked whenever the
          service provider detects any of the network events
          specified by the lEvent parameter. The socket for
          which notification is required is identified by s.
          The value of dwCallbackData will be passed back to
          the callerapplication as a parameter to the
          callback function.
          
          This function automatically sets socket s to non-
          blocking mode.
          
          The prototype of the callback function is as
          follows:
          
               VOID WSACALLBACK CallbackFunc( SOCKET s, long
          lEvent, int    ErrorCode, DWORD dwCallbackData );
          
          CallbackFunc is a placeholder for athe Winsock DLL
          supplied function pointername. The actual callback
          function must reside in a DLL or application
          module and be exported in the module definition
          file.  You must use MakeProcInstance() to get a
          procedure-instance address for the callback
          function.  The callback function ismust be written
          in such a way that it can be called by the
          provider from within interrupt context2. (This
          means that the only Winsock SPI calls that may be
          made within the callback function are WSPSend(),
          WSPsend(), WSPSendTo(), WSPsendto(), WSPRecv(),
          WSPrecv(), and WSPRecvFrom() WSPrecvfrom()
          provided that the socket option SO_INTERRUPT for
          this socket s is TRUE and the MSG_INTERRUPT flag
          for these functions is set.)
          
          The lEvent parameter is constructed by or'ing any
          of the values specified in the following list.

               Value      Meaning
               FD_READ    Want to receive notification of
                          readiness for reading
               FD_WRITE   Want to receive notification of
                          readiness for writing
               FD_OOB     Want to receive notification of
                          the arrival of out-of-band data
               FD_ACCEPT  Want to receive notification of
                          incoming connections
               FD_CONNECT Want to receive notification of
                          completed connection
               FD_CLOSE   Want to receive notification of
                          socket closure
               FD_QOS     Want to receive notification of
                          Quality of Service (QOS) changes
               FD_GROUP_QOS    Want to receive notification
                          of socket group Quality of
                          Service (QOS) changes
               
               FD_CLEANUP     Want to receive notification
                         of completed clean-up operation
          Issuing a WSPCallbackSelect16() for a socket
          cancels any previous WSPCallbackSelect16() for the
          same socket. For example, to receive notification
          for both reading and writing, the Winsock DLL must
          call WSPCallbackSelect16() with both FD_READ and
          FD_WRITE, as follows:
          
          rc = WSPCallbackSelect16(s, lpfnCallback,
                    dwCallbackData, FD_READ|FD_WRITE,
                    lpErrno);
          
          It is not possible to specify different callback
          data for different events. The following code will
          not work; the second call will cancel the effects
          of the first, and only FD_WRITE events will be
          reported with dwCallbackData2:
          
          rc = WSPCallbackSelect16(s, lpfnCallback,
                    dwCallbackData1, FD_READ, lpErrno);
          rc = WSPCallbackSelect16(s, lpfnCallback,
                    dwCallbackData2, FD_WRITE, lpErrno);
          
          To cancel all notification - i.e., to indicate
          that the service provider should no long invoke
          the callback function related to network events on
          the socket - lEvent should be set to zero. In this
          case, lpfnCallback and dwCallbackData are ignored.
          
          rc = WSPCallbackSelect16(s, lpfnCallback,
                    dwCallbackData, 0, lpErrno);
          
          Closing a socket with
          WSPCloseSocketWSPclosesocket() also cancels
          WSPCallbackSelect16() mechanism on the socket.
          
          A WSPAccept()'ed socket has the same properties as
          the listening socket used to accept it except that
          no network events and callback function are
          associated with it. Winsock2.DLL will subsequently
          invoke WSPCallbackSelect16() to register interest
          in the appropriate set of events for the
          WSPAccept()'ed socket3.Since a PSAcceptEx()'ed
          socket has the same properties as the listening
          socket used to accept it, any PSCallbackSelect()
          events set for the listening socket apply to the
          accepted socket.  For example, if a listening
          socket has PSCallbackSelect() events FD_ACCEPT,
          FD_READ, and FD_WRITE, then any socket accepted on
          that listening socket will also have FD_ACCEPT,
          FD_READ, and FD_WRITE events with the same
          callback function.  If a different callback
          function or events are desired, PII.DLL should
          call PSCallbackSelect(), passing the accepted
          socket and the desired new information.
          
          When one of the nominated network events occurs on
          the specified socket s, the callback function will
          be invoked. The s argument identifies the socket
          on which a network event has occurred. The lEvent
          argument specifies the network event that has
          occurred. The ErrorCode argument contains any
          error code. The error code can be any error as
          defined in ws2spi.h.
          
          The possible network event codes which may be
          returned are as follows:
          
               Value      Meaning
               FD_READ    Socket s ready for reading
               FD_WRITE   Socket s ready for writing
               FD_OOB     Out-of-band data ready for
               reading on socket s.
               FD_ACCEPT  Socket s ready for accepting a
                          new incoming connection
               FD_CONNECT Connection initiated on socket s
                          completed
               FD_CLOSE   Connection identified by socket s
                          has been closed
               FD_QOS     Quality of Service associated
                          with socket s or the socket group
                          to which s belongs has been
                          changed.
               FD_GROUP_QOS    Quality of Service
                          associated with the socket group
                          to which s belongs has changed.
               
          
Return Value   The return value is 0 if the Winsock's
          declaration of interest in the network event set
          was successful. Otherwise the value SOCKET_ERROR
          is returned, and a specific error number is
          available in lpErrno.

Comments  Although WSPCallbackSelect16() can be called with
          interest in multiple events, the Winsock DLL will
          get a callback for each network event.
          
          As in the case of WSPSelectWSPselect(),
          WSPCallbackSelect16() isare frequently used to
          determine when a data transfer operation
          (WSPSendWSPPSsend() or WSPRecvWSPrecv()) can be
          issued with the expectation of immediate success.
          
          The Winsock service provider will not continually
          flood the Winsock DLL with callbacks for a
          particular network event on a given socket. Having
          successfully invoked a callback indicating a
          particular event to the Winsock DLL, no further
          callback(s) for that network event on the socket
          will be invoked to the Winsock DLL until the
          Winsock DLL makes the function call which
          implicitly reenables notification of that network
          event, and returns from the callback function4.

          Event          Re-enabling function
          FD_READ        WSPRecvWSPrecv() or
                         WSPRecvFromWSPrecvfrom()
          FD_WRITE       WSPSendWSPsend() or
                         WSPSendToWSPsendto() or
                         WSAGetBuffer()
          FD_OOB         WSPRecvWSPrecv()
          FD_ACCEPT      WSPAccept() unless the error code
                         returned is WSATRY_AGAIN indicating
                         that the condition function
                         returned CF_DEFER
          FD_CONNECT     NONE
          FD_CLOSE       NONE
          FD_QOS         WSPGetSockOptWSPgetsockopt() with
                         option SO_FLOWSPEC
          
          FD_GROUP_QOS   WSPGetSockOptWSPgetsockopt() with
                         option SO_GROUP_FLOWSPEC
          
          Any call to the reenabling routine, even one which
          fails (except in the case of FD_ACCEPT when
          WSPAccept() returns with error code WSATRY_AGAIN),
          results in reenabling of callback invocation for
          the relevant event.
          
          For FD_READ, FD_OOB, FD_ACCEPT, FD_QOS and
          FD_GROUP_QOS events, callback invocation is "level-
          triggered." This means that if the reenabling
          routine is called and the relevant event is still
          valid after the call, an additional callback is
          invoked after the previous callback returns. This
          allows applications using Winsock2.DLL to be event-
          driven and not be concerned with the amount of
          data that arrives at any one time. Consider the
          following sequence:
          
          (i)       The service provider receives 100 bytes
                    of data on socket s and invokes an
                    FD_READ callback.
          (ii)      The Winsock2.DLL issues WSPRecvWSPrecv(
                    s, buffptr, 50, 0, lpErrno) to read 50
                    bytes.
          (iii)     The service provider invokes another
                    FD_READ callback since there is still
                    data to be read.
          
          With these semantics, the Winsock DLL need not
          read all available data in response to an FD_READ
          callback--a single WSPRecvWSPrecv() in response to
          each FD_READ callback is appropriate. If the
          Winsock DLL issues multiple WSPRecvWSPrecv() calls
          in response to a single FD_READ, it may receive
          multiple FD_READ callbacks.
          
          If an event has already happened when the Winsock
          DLL calls WSPCallbackSelect16()5 or when the
          reenabling function is called, then a callback is
          invoked as appropriate. All the events have
          persistence beyond the occurrence of their
          respective events. For example, if the Winsock DLL
          calls WSPListenWSPlisten(), a connect attempt is
          made, then the Winsock DLL calls
          WSPCallbackSelect16() specifying that it wants to
          receive FD_ACCEPT callbacks for the socket, the
          service provider invokes an FD_ACCEPT callback
          immediately.
          
          The FD_WRITE event is handled slightly
          differently. An FD_WRITE callback is invoked when
          a socket is first connected with WSPConnect() or
          accepted with WSPAccept, and then after a
          WSPSendWSPsend() or WSPSendToWSPsendto(), or
          WSAGetBuffer() fails with WSAEWOULDBLOCK and
          buffer space becomes available. Therefore, the
          Winsock DLL can assume that sends are possible
          starting from the first FD_WRITE callback and
          lasting until a send returns WSAEWOULDBLOCK. After
          such a failure the Winsock DLL will be notified
          that sends are again possible with an FD_WRITE
          callback.
          
          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 Winsock DLL should
          register an interest in, and will receive, FD_READ
          events, not FD_OOB events. The Winsock DLL may set
          or inspect the way in which out-of-band data is to
          be handled by using WSPSetSockOptWSPsetsockopt()
          or WSPGetSockOptWSPgetsockopt() for the
          SO_OOBINLINE option.
          
          The error code in an FD_CLOSE callback 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 WSAECONNRESET, then
          the socket's virtual circuit was reset. This only
          applies to connection-oriented sockets such as
          SOCK_STREAM.
          
          The FD_CLOSE callback is invoked when a close
          indication is received for the virtual circuit
          corresponding to the socket. In TCP terms, this
          means that the FD_CLOSE callback is invoked when
          the connection goes into the FIN WAIT or CLOSE
          WAIT states. This results from the remote end
          performing a WSPShutdownWSPshutdown() on the send
          side or a WSPCloseSocketWSPclosesocket().
          
          Please note the Winsock DLL shouldwill receive
          ONLY an FD_CLOSE callback to indicate closure of a
          virtual circuit. It shouldwill NOT receive an
          FD_READ callback to indicate this condition.
          
          The FD_QOS or FD_GROUP_QOS callback is invoked
          when any field in the flow spec associated with
          socket s or the socket group to which s belongs
          has changed, respectively. Winsock2.DLL should use
          WSPGetSockOptWSPgetsockopt() with option
          SO_FLOWSPEC or SO_GROUP_FLOWSPEC to get the
          current QOS for socket s or for the socket group
          to which s belongs, respectively.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this API.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           Indicates that one of the
                              specified parameters was
                              invalid, or the specified
                              socket is in an invalid state.
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEFAULT           The lpfnCallback is not part
                              of the user address space.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.

          Additional error codes may be set when the Winsock
          DLL receives a callback. Possible error codes for
          each network event are:
          Event: FD_CONNECT
          Error Code          Meaning
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAECONNREFUSED     The attempt to connect was
                              forcefully rejected.
          
          WSAEDESTADDRREQ     A destination address is
                              required.
          
          WSAEFAULT           The namelen argument is
                              incorrect.
          
          WSAEINVAL           The socket is already bound to
                              an address.
          
          WSAEISCONN          The socket is already
                              connected.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAENOTCONN         The socket is not connected.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAETIMEDOUT        Attempt to connect timed out
                              without establishing a
                              connection

          Event: FD_CLOSE
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAECONNRESET       The connection was reset by
                              the remote side.
          
          WSAECONNABORTED     The connection was aborted due
                              to timeout or other failure.
          
          Event: FD_READ
          Event: FD_WRITE
          Event: FD_OOB
          Event: FD_ACCEPT
          Event: FD_QOS
          Event: FD_GROUP_QOS
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          
Notes For
Winsock Service
Providers When a socket is closed, the Winsock service
          provider should cancel any pending callbacks to
          the Winsock DLL.
3.1.2.14 WSPCancelBlockingCall32()

Description    Cancel a blocking call which is currently in
          progress.

          #include <ws2spi.h>

          int WSPAPI WSPCancelBlockingCall32 ( int FAR *
          lpErrno );
          
          lpErrno   A pointer to the error code.

Remarks   This function is only applicable toavailable in
the 32-bit SPI.
          
          This function cancels any outstanding blocking
          operation for the current thread. It is normally
          used in two situations:
          
            1.   An application is processing a message which has been
               received while a blocking call is in progress. In this case,
               WSPIsBlocking32() will be TRUE.
            2.   A blocking call is in progress, and Winsock has called
               back to the applications "blocking hook" function (as
               established by WSPSetBlockingHook32()).
          
          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. In (2), the blocking call will be
          terminated as soon as the blocking hook function
          completes.)
          
          In the case of a blocking WSPConnect() operation,
          the Windows Sockets implementation will terminate
          the blocking call as soon as possible, but 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
          available), or to WSPConnect() to the same peer.
          
          Cancelling an WSPAccept() or a
          WSPSelectWSPselect() call does not adversely
          impact the sockets passed to these calls. Only the
          particular call fails; any operation that was
          legal before the cancel is legal after the cancel,
          and the state of the socket is not affected in any
          way.
          
          Cancelling any operation other than WSPAaccept()
          and WSPSelectWSPselect() 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
          WSPCloseSocketWSPclosesocket(), although other
          operations may work on some service provider
          Windows Sockets implementations. If 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.
          
          If a cancel operation compromised 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 WSPCloseSocketWSPclosesocket() with
          WSAECONNABORTED.

Return Value   The return value is 0 if the blocking
          operation has been successfully cancelled.
          Otherwise the value SOCKET_ERROR is returned, and
          a specific error number is available in lpErrno.
          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          

Comments  Note that it is possible that the network
          operation completes before the
          WSPCancelBlockingCall32() 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
          WSPCancelBlockingCall32() had never been called.
          Note that the WSPCancelBlockingCall32() still
          succeeds in this case; the only way to know with
          certainty that an operation was actually canceled
          is to check for a return code of WSAEINTR from the
          blocking call.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The Windows Sockets
                              implementation has detected
                              that the network subsystem has
                              failed.
          
          WSAEINVAL           Indicates that there is no
                              outstanding blocking call.
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.

See Also  WSPIsBlocking32(), WSPSetBlockingHook32(),
          WSPUnhookBlockingHook32()
PSCancelBlockingCall()
Description    Cancel a blocking call which is currently in
          progress.

          #include <PII.h>

          int PASCAL FAR PSCancelBlockingCall ( void );

Remarks   This function cancels any outstanding blocking
          operation for this task.  It is normally used in
          two situations:
          
          (1) An application is processing a message which
          has been received while a blocking call is in
          progress.  In this case, PSIsBlocking() will be
          true.
          
          (2) A blocking call is in progress, and PII has
          called back to the application's "blocking hook"
          function (as established by PSSetBlockingHook()).
          
          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 PII.
          In (2), the blocking call will be terminated as
          soon as the blocking hook function completes.)
          
          In the case of a blocking PSconnect() operation,
          the PII Service Provider will terminate the
          blocking call as soon as possible, but 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
          available), or to PSconnect() to the same peer.
          
          Canceling an PSaccept() or a PSselect() call does
          not adversely impact the sockets passed to these
          calls.  Only the particular call fails; any
          operation that was legal before the cancel is
          legal after the cancel, and the state of the
          socket is not affected in any way.
          
          Canceling any operation other than PSaccept() and
          PSselect() 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
          PSclosesocket(), although other operations may
          work on some PII Service Providers.  If 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.
          
          If a cancel operation compromised the integrity of
          a SOCK_STREAM's data stream in any way, the PII
          Service Provider must reset the connection and
          fail all future operations other than
          PSclosesocket() with WSAECONNABORTED.

Return Value   The value returned by PSCancelBlockingCall()
          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 PSGetLastError().

Comments  Note that it is possible that the network
          operation completes before the
          PSCancelBlockingCall()  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
          PSCancelBlockingCall() had never been called.
          Note that the PSCancelBlockingCall() still
          succeeds in this case; the only way to know with
          certainty that an operation was actually canceled
          is to check for a return code of WSAEINTR from the
          blocking call.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The PII Service Provider has
                              detected that the network
                              subsystem has failed.
          
          WSAEINVAL           Indicates that there is no
                              outstanding blocking call.

3.1.2.15 WSPCleanup()

Description    Terminate use of the Winsock service
          provider.

          #include <ws2spi.h>

          int WSPAPI WSPCleanup ( LPCLEANUPPROC
          lpfnCallback, DWORD dwCallbackData, int FAR *
          lpErrno );
          
          lpfnCallback   The address of the callback
                    function to be invoked by the service
                    provider when the cleanup operation
                    completed.
          
          dwCallbackData The callback data passed back to
                    the Winsock DLL along with the callback.
                    This object is not interpreted by the
                    Winsock service provider.
          
          lpErrno   A pointer to the error code.

Remarks   The Winsock DLL is required to perform a
          (successful) WSPStartup() call before it can use
          Winsock service providers. When it has completed
          the use of Winsock service providers, the Winsock
          DLL must call WSPCleanup() to deregister itself
          from a Winsock service provider and allow the
          service provider to free any resources allocated
          on behalf of the Winsock DLL. Any open connection-
          oriented sockets that are connected when
          WSPCleanup() is called are reset; sockets which
          have been closed with
          WSPCloseSocketWSPclosesocket() but which still
          have pending data to be sent are not affected--the
          pending data is still sent. When the cleanup
          operation is finished, the specified callback
          function will be invoked. The value of
          dwCallbackData will be passed back to the Winsock
          DLL along with the callback.
          
          The prototype of the callback function is as
          follows:
          
               VOID WSACALLBACK CallbackFunc( int ErrorCode,
          DWORD dwCallbackData );
          
          CallbackFunc is a placeholder for athe Winsock DLL-
          supplied function pointername. The callback
          function is only called when the client thread
          that invoked this SPI is blocked in an alertable
          wait. The callback data is passed back to the
          Winsock DLL along with the callback. This object
          is not interpreted by the Winsock service
          provider.
          
          {I'm not convinced this is sufficient. Perhaps if
          the first call to WSPCleanup() returns
          WSAEWOULDBLOCK, then the Winsock DLL must wait for
          the callback to be invoked before unloading the
          provider DLL. Under Win32, the Winsock DLL would
          need to be blocked in an alertable wait for the
          callback (really a user-mode APC) to be invoked.
          The callback routine (in the Winsock DLL) could
          signal an event, waking the main thread. The main
          thread could then unload the DLL. Just a
          thought...}
          
          There must be a call to PSCleanup() for every call
          to PSStartup() made by a task.  Only the final
          PSCleanup() for that task does the actual cleanup;
          the preceding calls simply decrement an internal
          reference count in the PII service provider.  A
          naive application may ensure that PSCleanup() was
          called enough times by calling PSCleanup() in a
          loop until it returns WSANOTINITIALISED.

Return Value   The return value is 0 if the operation has
          been successfully initiated. Otherwise the value
          SOCKET_ERROR is returned, and a specific error
          number is available in lpErrno.
          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          

Comments  Attempting to call PSCleanup() from within a
          blocking hook and then failing to check the return
          code is a common PII programming error.  If an
          application needs to quit while a blocking call is
          outstanding, the application must first cancel the
          blocking call with PSCancelBlockingCall() then
          issue the PSCleanup() call once control has been
          returned to the application.

Notes For
Winsock Service
Providers The Winsock DLL will make one and only one
          WSPCleanup() call to indicate deregistration from
          a Winsock service provider. This function can
          thus, for example, be utilized to free up
          allocated resources. {Yeah, but since each
          protocol is represented as a separate service
          provider, it's possible that the service
          provider's DLL which implements multiple protocols
          (e.g. TCP and UDP) could be called with
          WSPCleanup() multiple times} {We have basically
          two choices here. We could either a) make separate
          WSPStartup() and WSPCleanup() calls for each
          protocol/address_family/socket_type triple
          supported by a given service provider DLL, or b)
          provide a single WSPStartup() call when a service
          provider is first loaded, and a single
          WSPCleanup() when its time to close shop. I tend
          to favorfavour b), as it places the burden of
          responsibility on the Winsock DLL, where it's
          easier to control & get right (once).}

          A PII service provider must be prepared to deal
          with an application which terminates without
          invoking PSCleanup() - for example, as a result of
          an error.
          
          In a multithreaded environment, WSPCleanup()
          terminates Winsock operations for all threads.
          
          A Winsock service provider must ensure that
          WSPCleanup() leaves things in a state in which the
          Winsock DLL can invoke WSPStartup() to re-
          establish Winsock usage.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The lpfnCallback is not part
                              of the user address space.
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.

See Also  WSPStartup()
3.1.2.16 WSPConnect()

Description    Establish a connection to a peer, create
          and/or join a socket group, and specify needed
          quality of service based on the supplied flow
          spec.

          #include <ws2spi.h>

          int WSPAPI WSPConnect ( SOCKET s, const struct
          sockaddr FAR * name, int namelen, LPWSABUF
          lpCallerData, LPWSABUF lpCalleeData, GROUP g,
          LPQOS lpSFlowspec, int iSFlowspecLen, LPQOS
          lpGFlowspec, int iGFlowspecLen, int FAR * lpErrno
          );

          
          s          A descriptor identifying an unconnected
                    socket.
          
          name      The name of the peer to which the socket
                    is to be connected.
          
           namelen  The length of the name.
          
          lpCallerData   A pointer to the user data that is
                    to be transferred to the peer during
                    connection establishment.
          
          lpCalleeData   A pointer to the user data that is
                    to be transferred back from the peer
                    during connection establishment.
          
          g         The identifier of the socket group.
          
          lpSFlowspec    A pointer to the flow specs for
                    socket s, one for each direction, if s
                    is a DSTREAM type socket. Otherwise,
                    this parameter is ignored.
          
          iSFlowspecLen  The length of the flow spec for
                    socket s, if s is unidirectional and
                    DSTREAM type socket.  Otherwise, this
                    parameter is ignored.
          
          lpGFlowspec    A pointer to the flow specs for the
                    socket group to be created, one for each
                    direction, if the value of parameter g
                    is SG_CONSTRAINED_GROUP. Otherwise, this
                    parameter is ignored.
          
          lpErrno   A pointer to the error code.
          
          iGFlowspecLen  The length of the flow spec for the
                    socket group to be created, if the value
                    of parameter g is SG_CONSTRAINED_GROUP.
                    Otherwise, this parameter is ignored.

Remarks   This function is used to create a connection to
          the specified destination, and to perform a number
          of other ancillary operations that occur at
          connect time as well. For connection-oriented
          sockets (e.g., type SOCK_STREAM), an active
          connection is initiated to the foreign host using
          name (an address in the name space of the socket;
          for a detailed description, please see
          WSPBindWSPbind()). When this call completes
          successfully, the socket is ready to send/receive
          data.
          
          For a connectionless socket (e.g., type
          SOCK_UNREL_DGRAM), the operation performed by
          WSPConnect() is merely to establish a default
          destination address which will be used on
          subsequent WSPSendWSPsend() and WSPRecvWSPrecv()
          calls. Exchange of user to user data and QOS
          specification are not possible and the
          corresponding parameters will be ignored.
          
          If the socket, s, 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 name structure is all
          zeroes, WSPConnect() will return the error
          WSAEADDRNOTAVAIL.
          
          The Winsock DLL is responsible for allocating any
          memory space pointed to directly or indirectly by
          any of the parameters it specified. LPWSABUF and
          LPQOS are defined in ws2spi.h as follows:
          
               typedef struct _WSABUF {
                    int       len;      // the length of the
          buffer
                    char FAR *     buf; // the pointer to
          the buffer
               } WSABUF, FAR * LPWSABUF;
          
               typedef enum
               {
                    GuaranteedService,
                    BestEffortService
               } GUARANTEE;

               typedef struct _flowparams
               {
                    int64          AverageBandwidth;// In
Bytes/sec
                         int64          PeakBandwidth; // In
Bytes/sec
                         int64          BurstLength;   // In
microseconds
                    int64          Latency;       // In
microseconds
                    int64          DelayVariation;     // In
microseconds
                    GUARANTEE levelOfGuarantee;// Guaranteed
or
                                        // Best Effort
                    int32          CostOfCall;    //
Reserved for future
                                        // use, must be set
to 0
                    int32          ProviderId;    //
Provider Identifier
                    int32          SizePSP;  // Length of
provider
                                        // specific
parameters
                         UCHAR
ProviderSpecificParams[1];// provider specific
// parameters
               } FLOWPARAMS;

               typedef struct _QualityOfService
               {
                    FLOWPARAMS     ForwardFP;     //
Caller(Initiator) to callee
                    FLOWPARAMS     BackwardFP;    // Callee
to caller
               } QOS, FAR * LPQOS;
          
          The lpCallerData is a value parameter which
          contains any user data that is to be sent along
          with the connection request. If lpCallerData is
          NULL, no user data will be passed to the peer. The
          lpCalleeData is a result parameter which will
          contain any user data passed back from the peer as
          part of the connection establishment. If
          lpCalleeData->len is 0, no user data has been
          passed back. The lpCalleeData information will be
          valid when the connection operation is complete,
          i.e., after the FD_CONNECT notification has
          occurred. If lpCalleeData is NULL, no user data
          will be passed back. The exact format of the user
          data is specific to the address family to which
          the socket belongs.
          
          Parameter g is used to indicate the appropriate
          actions on socket groups:
               if g is an existing socket group id, add s to
          this group, provided all the
          requirements set by this group are met; or
               if g = SG_UNCONSTRAINED_GROUP, create an
          unconstrained socket               group and have
          s as the first member; or
               if g = SG_CONSTRAINED_GROUP, create a
          constrained socket group and            have s as
          the first member; or
               if g = NULL, no operation is performed, and
          is equivalent to connect().
          For unconstrained group, any set of sockets may be
          grouped together as long as they are supported by
          a single Winsock service provider and are
          connection-oriented. A constrained socket group
          requires that connections on all grouped sockets
          be to the same host. For newly created socket
          groups, the new group id can be retrieved by using
          WSPGetSockOptWSPgetsockopt() with option
          SO_GROUP_ID, if this operation completes
          successfully.
          
          lpSFlowspec, and iSFlowspecLen specifies two
          blocks of memory containing the flow specs for
          socket s, one for each direction, if s is a
          DSTREAM type socket. Otherwise, these values are
          ignored. The forward QOS or backward QOS values
          will be ignored as appropriate for unidirectional
          sockets. for UNI_RECV type socket. The backward
          QOS value will be ignored for UNI_SEND type
          socket. The first part of each memory block is
          struct FLOWSPEC, optionally followed by any
          service provider specific portion. Thus,
          lpSFlowspec->Flen and lpSFlowspec->Blen must be
          larger than or equal to the size of struct
          FLOWSPEC. A NULL value for lpSFlowspec indicates
          no application supplied flow spec.
          
          lpGFlowspec, and iGFlowspecLen specifies two
          blocks of memory containing the flow specs for the
          socket group to be created, one for each
          direction, provided that the value of parameter g
          is SG_CONSTRAINED_GROUP. Otherwise, these values
          are ignored. The first part of each memory block
          is struct FLOWSPEC, optionally followed by any
          service provider specific portion. Thus,
          lpGFlowspec->Flen and lpGFlowspec->Blen must be
          larger than or equal to the size of struct
          FLOWSPEC. A NULL value for lpGFlowspec indicates
          no application supplied flow spec.
          
Comments  When connected sockets break (i.e. become closed
          for whatever reason), they should be discarded and
          recreated. It is safest to assume that when things
          go awry for any reason on a connected socket, the
          Winsock DLL must discard and recreate the needed
          sockets in order to return to a stable point.

Return Value   If no error occurs, WSPConnect() returns 0.
          Otherwise, it returns SOCKET_ERROR, and a specific
          error code is available in lpErrno.

          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          
Error Codes    The following errors may occur at the time of
          the function call, and indicate that the connect
          operation could not be initiated.

WSANOTINITIALISED             A successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              PSCancelBlockingCall().
          
          WSAEINPROGRESS      The function is invoked when a
                              callback is in progress.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAEDESTADDREQ      A destination address is
                              required.
          
          WSAEFAULT           The namelen argument is
                              incorrect, the buffer length
                              for lpCalleeData, lpSFlowspec,
                              and lpGFlowspec are too small,
                              or the buffer length for
                              lpCallerData is too large.
          
          WSAEINVAL           The parameter g specified in
                              the condition function is not
                              a valid value, or the
                              parameter s is a listening
                              socket.
          
          WSAEISCONN          The socket is already
                              connected.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEPROTONOSUPPORT  The lpCallerData augment is
                              not supported by the service
                              provider.
          
          WSAEWOULDBLOCK      The socket is marked as non-
                              blocking and the connection
                              cannot be completed
                              immediately.  It is possible
                              to PSselect() the socket while
                              it is connecting by
                              PSselect()ing it for writing.


          The following error codes may be returned by
          WSPEnumNetworkEvents() after the connect has
          completed.

WSANOTINITIALISED             A successful PSStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              PSCancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII call is in
                              progress.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAECONNREFUSED     The attempt to connect was
                              forcefully rejected.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAEOPNOTSUPP       The flow specs specified in
                              lpSFlowspec and lpGFlowspec
                              cannot be satisfied.
          
          WSAETIMEDOUT        Attempt to connect timed out
                              without establishing a
                              connection

See Also  WSPAccept(), WSPBindWSPbind(),
          WSPGetSockNameWSPgetsockname(),
          WSPGetSockOptWSPgetsockopt(), WSPsocket(),
          WSPSelectWSPselect(), WSPEventSelect(),
          WSPEnumNetworkEvents().
3.1.2.17 WSPEnumNetworkEvents()

Description    Discover occurrences of network events for
          the indicated socket.

          #include <ws2spi.h>

          int WSPAPI WSPEnumNetworkEvents ( SOCKET s,
          WSAEVENT hEventObject, LPWSANETWORKEVENT
          lpNetworkEvents, LPINT lpiCount, int FAR * lpErrno
          );

          s          A descriptor identifying the socket.
          
          hEventObject   An optional handle identifying an
                    associated event object to be reset.
          
          lpNetworkEvents     An array of WSANETWORKEVENT
                    structs, each of which records an
                    occurred network event and the
                    associated error code.
          
          lpiCount  The number of elements in the array.
                    Upon returning, this parameter indicates
                    the actual number of elements in the
                    array, or the minimum number of elememts
                    needed to retrieve all the network
                    events if the return value is
                    WSAENOBUFS.
          
          lpErrno   A pointer to the error code.

Remarks   This function is used to discover which network
          events have occurred for the indicated socket
          since the last invocation of this function. It is
          intended for use in conjunction with
          WSPEventSelect(), which associates an event object
          with one or more network events. The socket's
          internal record of network events is copied to
          lpNetworkEvents, whereafter the internal network
          events record is cleared. If hEventObject is non-
          null, the indicated event object is also reset.
          The Winsock2 DLL guarantees that the operations of
          copying the network event record, clearing it and
          resetting any associated event object are atomic,
          such that the next occurrence of a nominated
          network event will cause the event object to
          become set.
          
          The following error codes may be returned along
          with the respective network event:
          Event: FD_CONNECT
          Error Code          Meaning
          WSAEADDRINUSE       The specified address is
                              already in use.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAECONNREFUSED     The attempt to connect was
                              forcefully rejected.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be
                              connected.
          
          WSAETIMEDOUT        Attempt to connect timed out
                              without establishing a
                              connection

          Event: FD_CLOSE
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAECONNRESET       The connection was reset by
                              the remote side.
          
          WSAECONNABORTED     The connection was aborted due
                              to timeout or other failure.
          
          Event: FD_READ
          Event: FD_WRITE
          Event: FD_OOB
          Event: FD_ACCEPT
          Event: FD_QOS
          Event: FD_GROUP_QOS
          Error Code          Meaning
          WSAENETDOWN         The network subsystem has
                              failed.
          
Return Value   The return value is 0 if the operation was
          successful. Otherwise the value SOCKET_ERROR is
          returned, and a specific error number is available
          in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           Indicates that one of the
                              specified parameters was
                              invalid
          
          WSAEINPROGRESS      A blocking Winsock call is in
                              progress, or the service
                              provider is still processing a
                              callback function (see section
                              ???).

          WSAENOBUFS          The supplied buffer is too
                              small.
          
See Also  WSPEventSelect()
3.1.2.18 WSPEventSelect()

Description    Specify an event object to be associated with
          the supplied set of FD_XXX network events.

          #include <ws2spi.h>

          int WSPAPI WSPEventSelect ( SOCKET s, WSAEVENT
          hEventObject, long lNetworkEvents, int FAR *
          lpErrno );

          s          A descriptor identifying the socket.
          
          hEventObject   A handle identifying the event
                    object to be associated with the
                    supplied set of FD_XXX network events.
          
          lNetworkEvents A bitmask which specifies the
                    combination of FD_XXX network events in
                    which the application has interest.
          
          lpErrno   A pointer to the error code.

Remarks   This function is used to specify an event object,
          hEventObject, to be associated with the selected
          FD_XXX network events, lNetworkEvents. The socket
          for which an event object is specified is
          identified by s. The event object is set when any
          of the nominated network events occuroccurr.

          WSPEventSelect() operates very similarly to
          WSPAsyncSelect32(), the difference being in the
          actions taken when a nominated network event
          occurs. Whereas WSPAsyncSelect32() causes an
          application-specified Windows message to be
          posted, WSPEventSelect() sets the associated event
          object and records the occurrence of this event by
          setting the corresponding bit in an internal
          network event record. An application can use
          WSAWaitForMultipleEvents() or
          WSAGetOverlappedResult() to wait or poll on the
          event object, and use WSAEnumNetworkEvents() to
          retrieve the contents of the internal network
          event record and thus determine which of the
          nominated network events have occurred.
          
          This function automatically sets socket s to non-
          blocking mode, regardless of the value of
          lNetworkEvents. See WSPIoctlSocketWSPioctlsocket()
          about how to set the socket back to blocking mode.
          
               FD_ACCEPT Want to receive notification of
                         incoming connections
               FD_CONNECT     Want to receive notification
                         of completed connection
               FD_CLOSE  Want to receive notification of
                         socket closure
          The lNetworkEvents parameter is constructed by
          or'ing any of the values specified in the
          following list.

               Value      Meaning
               FD_READ    Want to receive notification of
                          readiness for reading
               FD_WRITE   Want to receive notification of
                          readiness for writing
               FD_OOB     Want to receive notification of
                          the arrival of out-of-band data
               FD_ACCEPT  Want to receive notification of
                          incoming connections
               FD_CONNECT Want to receive notification of
                          completed connection
               FD_CLOSE   Want to receive notification of
                          socket closure
               FD_QOS     Want to receive notification of
                          socket Quality of Service (QOS)
                          changes
               FD_GROUP_QOS    Want to receive notification
                          of socket group Quality of
                          Service (QOS) changes
               

          Issuing a WSPEventSelect() for a socket cancels
          any previous WSPAsyncSelect32() or
          WSPEventSelect() for the same socket and clears
          all bits in the internal network event record. For
          example, to associate an event object with both
          reading and writing network events, the
          application must call WSPEventSelect() with both
          FD_READ and FD_WRITE, as follows:
          
          rc = WSPEventSelect(s, hEventObject,
                    FD_READ|FD_WRITE);
          
          It is not possible to specify different event
          objects for different network events. The
          following code will not work; the second call will
          cancel the effects of the first, and only FD_WRITE
          network event will be associated with
          hEventObject2:
          
          rc = WSPEventSelect(s, hEventObject1, FD_READ);
          rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
          
          To cancel the association and selection of network
          events on a socket, lNetworkEvents should be set
          to zero, in which case the hEventObject parameter
          will be ignored.
          
          rc = WSPEventSelect(s, hEventObject, 0);
          
          Closing a socket with
          WSPCloseSocketWSPclosesocket() also cancels the
          association and selection of network events
          specified in WSPEventSelect() for the socket. The
          application, however, still needs to call
          WSACloseEvent() to explicitly close the event
          object and free any resources.
          
          Since a WSAAccept()'ed socket has the same
          properties as the listening socket used to accept
          it, any WSPEventSelect() association and network
          events selection set for the listening socket
          apply to the accepted socket. For example, if a
          listening socket has WSPEventSelect() association
          of hEventOject with FD_ACCEPT, FD_READ, and
          FD_WRITE, then any socket accepted on that
          listening socket will also have FD_ACCEPT,
          FD_READ, and FD_WRITE network events associated
          with the same hEventObject. If a different
          hEventObject or network events are desired, the
          application should call WSPEventSelect(), passing
          the accepted socket and the desired new
          information.6

Return Value   The return value is 0 if the application's
          specification of the network events and the
          associated event object was successful. Otherwise
          the value SOCKET_ERROR is returned, and a specific
          error number is available in lpErrno.

Comments  The scenarios that an event object is signaled is
          dependent on the associated network events.  The
          scenarios for each network event are listed below:

          Event          Scenarios the associated event
                         object get signaled
          FD_READ        When data arrives in an emply
                         transport internal queue, or at the
                         end of the recv()/recvfrom() call
                         if there is more data to be read.
          FD_WRITE       When a socket is first connected
                         with connect() or accepted with
                         accept(), or after a send() or
                         sendto(), or WSAGetBuffer() fails
                         with WSAEWOULDBLOCK and buffer
                         space becomes available or
                         WSAGetBuffer()
          FD_OOB         The same as FD_READ, but with out-
                         of-band data.
          FD_ACCEPT      When an incoming connection request
                         arrives, or at the end of accept()
                         or WSAAcceptEx() (unless the error
                         code returned is WSATRY_AGAIN) if
                         there are more incoming connection
                         requests.
          FD_CONNECT     When the connect operation
                         completed.
          FD_CLOSE       When the remote side closes the
                         virtual circuit and the application
                         has read all bufferred data for the
                         socket.
          FD_QOS         When the socket QOS changes.
          FD_GROUP_QOS   When the group QOS changes.
          
          If an network event has already happened when the
          application calls WSAEventSelect(), then the
          associated event object get signaled as
          appropriate.
          
          As in the case of the WSPSelectWSPselect() and
          WSPAsyncSelect32() functions, WSPEventSelect()
          will frequently be used to determine when a data
          transfer operation (WSPSendWSPsend() or
          WSPRecvWSPrecv()) can be issued with the
          expectation of immediate success. Nevertheless, a
          robust application must be prepared for the
          possibility that the event object is set and it
          issues a Winsock call which returns WSAEWOULDBLOCK
          immediately. For example, the following sequence
          of operations is possible:
          
          (i)       data arrives on socket s; Winsock sets
                    the WSPEventSelect event object
          (ii)      application does some other processing
          (iii)     while processing, application issues an
          WSPIoctlSocketWSPioctlsocket(s,
                    FIONREAD...) and notices that there is
                    data ready to be read
          (iv)      application issues a
                    WSPRecvWSPrecv(s,...) to read the data
          (v)       application eventually waits on event
                    object specified in WSPEventSelect,
                    which returns immediately indicating
                    that data is ready to read
          (vi)      application issues
                    WSPRecvWSPrecv(s,...), which fails with
                    the error WSAEWOULDBLOCK.
          
          Other sequences are possible.
          
          Having successfully recorded the occurrence of the
          network event (by setting the corresponding bit in
          the internal network event record) and signaled
          the associated event object, no further actions
          are taken for that network event until the
          application makes the function call which
          implicitly reenables the setting of that network
          event and signaling of the associated event
          object.

          Network Event  Re-enabling function
          FD_READ        WSPRecvWSPrecv() or
                         WSPRecvFromWSPrecvfrom()
          FD_WRITE       WSPSendWSPsend() or
                         WSPSendToWSPsendto() or
                         WSAGetBuffer()
          FD_OOB         WSPRecvWSPrecv()
          FD_ACCEPT      WSPAccept() unless the error code
                         returned is WSATRY_AGAIN indicating
                         that the condition function
                         returned CF_DEFER
          FD_CONNECT     NONE
          FD_CLOSE       NONE
          FD_QOS         WSPGetSockOptWSPgetsockopt() with
                         option SO_FLOWSPEC
          FD_GROUP_QOS   WSPGetSockOptWSPgetsockopt() with
                         option SO_GROUP_FLOWSPEC
          
          Any call to the reenabling routine, even one which
          fails, results in reenabling of recording and
          setting for the relevant network event and event
          object, respectively.
          
          For FD_READ, FD_OOB, FD_ACCEPT, FD_QOS and
          FD_GROUP_QOS network events, network event
          recording and event object setting are "level-
          triggered." This means that if the reenabling
          routine is called and the relevant network
          condition is still valid after the call, the
          network event is recorded and the associated event
          object is set . This allows an application to be
          event-driven and not be concerned with the amount
          of data that arrives at any one time. Consider the
          following sequence:
          
          (i)       transport provider receives 100 bytes of
                    data on socket s and causes Winsock2 DLL
                    to record the FD_READ network event and
                    set the associated event object.
          (ii)      The application issues WSPRecvWSPrecv(
                    s, buffptr, 50, 0) to read 50 bytes.
          (iii)     The transport provider causes WINSOCK
                    DLL to record the FD_READ network event
                    and sets the associated event object
                    again since there is still data to be
                    read.
          
          With these semantics, an application need not read
          all available data in response to an FD_READ
          network event --a single WSPRecvWSPrecv() in
          response to each FD_READ network event is
          appropriate.  If an application issues multiple
          recv() calls in response to a single FD_READ, it
          may receive multiple FD_READ messages.  Such an
          application may wish to disable FD_READ messages
          before starting the recv() calls by calling
          WSAAsyncSelect() with the FD_READ event not set.
          
          If a network event has already happened when the
          application calls WSPEventSelect() or when the
          reenabling function is called, then a network
          event is recorded and the associated event object
          is set as appropriate. All the network events have
          persistence beyond the occurrence of their
          respective events. For example, consider the
          following sequence: 1) an application calls
          WSPListenWSPlisten(), 2) a connect request is
          received but not yet accepted, 3) the application
          calls WSPEventSelect() specifying that it is
          interested in the FD_ACCEPT network event for the
          socket. Due to the persistence of network events,
          Winsock records the FD_ACCEPT network event and
          sets the associated event object immediately.
          
          The FD_WRITE network event is handled slightly
          differently. An FD_WRITE network event is recorded
          when a socket is first connected with WSPConnect()
          or accepted with WSPAccept(), and then after a
          WSPSendWSPsend() or WSPSendToWSPsendto(), or
          WSAGetBuffer() fails with WSAEWOULDBLOCK and
          buffer space becomes available. Therefore, an
          application can assume that sends are possible
          starting from the first FD_WRITE network event
          settingsettting and lasting until a send returns
          WSAEWOULDBLOCK. After such a failure the
          application will find out that sends are again
          possible when an FD_WRITE network event is
          recorded  and the associated event object is set .
          
          The FD_OOB network 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 register an interest in, and
          will get, FD_READ network event, not FD_OOB
          network event. An application may set or inspect
          the way in which out-of-band data is to be handled
          by using WSPSetSockOptWSPsetsockopt() or
          WSPGetSockOptWSPgetsockopt() for the SO_OOBINLINE
          option.
          
          The error code in an FD_CLOSE network event
          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 WSAECONNRESET,
          then the socket's virtual circuit was reset. This
          only applies to connection-oriented sockets such
          as SOCK_STREAM.
          
          The FD_CLOSE network event is recorded when a
          close indication is received for the virtual
          circuit corresponding to the socket. In TCP terms,
          this means that the FD_CLOSE is recorded when the
          connection goes into the FIN WAIT or CLOSE WAIT
          states. This results from the remote end
          performing a WSPShutdownWSPshutdown() on the send
          side or a WSPCloseSocketWSPclosesocket().
          
          Please note Winsock will record ONLY an FD_CLOSE
          network event to indicate closure of a virtual
          circuit. It will NOT record an FD_READ network
          event to indicate this condition.
          
          The FD_QOS or FD_GROUP_QOS network event is
          recorded when any field in the flow spec
          associated with socket s or the socket group that
          s belongs to has changed, respectively.
          Applications should use
          WSPGetSockOptWSPgetsocketopt() with option
          SO_FLOWSPEC or SO_GROUP_FLOWSPEC to get the
          current QOS for socket s or for the socket group s
          belongs to, respectively.
          
Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEINVAL           Indicates that one of the
                              specified parameters was
                              invalid, or the specified
                              socket is in an invalid state.
          
          WSAEINPROGRESS      A blocking Winsock call is in
                              progress, or the service
                              provider is still processing a
                              callback function (see section
                              ???).
          
          WSAENOTSOCK         The descriptor is not a
                              socket.


See Also  WSPEnumNetworkEvents()
3.1.2.19 WSPIsBlocking32()

Description    Determine if a blocking call is in progress.

          #include <ws2spi.h>

          BOOL WSPAPI WSPIsBlocking32 ( VOID );

Remarks   This function is only applicable to the 32-bit
SPIis only available in the 32-bit SPI.
          
          This function allows the Winsock DLL to determine
          if it is executing while waiting for a previous
          blocking call to complete.
          
Return Value   The return value is TRUE if there is an
          outstanding blocking function awaiting completion.
          Otherwise, it is FALSE.
          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          

See Also  WSPCancelBlockingCall32(), WSPSetBlockingHook32(),
          WSPUnhookBlockingHook32()
3.1.2.210 WSPRrecv()

Description    Receive data from a socket. {warning! Since
          both the recv() and WSARecv() API functions map to
          this function the description needs to be more
          generic with respect to overlapped I/O This also
          applies to WSPRecvFromWSPrecvFrom, WSPSendWSPSend,
          WSPSendToWSPSendTo}

          #include <ws2spi.h>

          int WSPAPI WSPRecvWSPrecv ( SOCKET s, LPVOID
          lpBuffer, DWORD nNumberOfBytesToRecv, LPDWORD
          lpNumberOfBytesRecvd, LPINT lpFlags,
          LPWSAOVERLAPPED lpOverlapped,
          LPWSAOVERLAPPED_COMPLETION_ROUTINE
          lpCompletionRoutine, int FAR * lpErrno );

          
          s               A descriptor identifying an
                         overlapped, connected socket. which
                         was created using WSPSocket() with
                         flag WSA_FLAG_OVERLAPPED.
          
          lpBuffer       A pointer to the buffer for the
                         incoming data.
          
          nNumberOfBytesToRecv     The number of bytes to
                         receive from the network.
          
          lpNumberOfBytesRecvd     A pointer to the number
                         of bytes received by this call.
          
          lpFlags        A pointer to flags.
          
          lpOverlapped   A pointer to a WSAOVERLAPPED
                         structure.
          
          lpCompletionRoutine A pointer to the completion
                         routine called when the receive
                         operation has been completed.
          
          lpErrno        A pointer to the error code.

Remarks   This function is used on a connection-oriented
          socket specified by s to post a buffer into which
          incoming data will be placed as it becomes
          available. It can also be used on connectionless
          sockets which have a stipulated default peer
          address established via the WSPConnect()
          functions.
          
          For non-overlapped socket, this function behaves
          like the standard recv() API with identical
          blocking semantics and the lpOverlapped and
          lpCompletionRoutine parameters are ignored. The
          completion status of this SPI is the final
          completion status of the receive operation.
          
          For overlapped sockets, the final completion
          status is retrieved via the
          WSAGetOverlappedResult() API.

          For byte stream style sockets (e.g., type
          SOCK_STREAM), incoming data is placed into the
          buffer until the buffer is filled. If the socket
          has been configured for in-line reception of out-
          of-band data (socket option SO_OOBINLINE) and out-
          of-band data is unread, only out-of-band data will
          be filled.  The application may use the
          ioctlsocket() SIOCATMARK to determine whether any
          more out-of-band data remains to be read.
          
          For message-oriented sockets (e.g., type
          SOCK_DGRAM), an incoming message is placed into
          the supplied buffer, up to the size of the buffer
          supplied. If the message is larger than the buffer
          supplied, the buffer is filled with the first part
          of the message, the excess data is lost, and
          WSPRecvWSPrecv() indicatesreturns the error
          WSAEMSGSIZE.
          
          If no incoming data is available at the socket,
          the recv() 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 select(),
          WSAAsyncSelect() or WSACallbackSelect() calls may
          be used to determine when more data arrives.
          
          If the socket is connection-oriented and the
          remote side has shut down the connection
          gracefully, WSPRecvWSPrecv() will complete
          immediately indicating zero bytes received. If the
          connection has been reset, a WSPRecvWSPrecv() will
          fail with the error WSAECONNRESET.
          
          This function may be called from within the
          completion routine of a previous WSPRecvWSPrecv(),
          WSPRecvFromWSPrecvfrom(), WSPSendWSPsend() or
          WSPSendToWSPsendto() function.
          
          When called with an overlapped socket, the
          lpOverlapped parameter much be valid for the
          duration of the overlapped operation. The
          WSAOVERLAPPED structure has the following form:
          
               typedef struct _WSAOVERLAPPED {
                    DWORD          Internal;      //
          reserved
                    DWORD          InternalHigh;  //
          reserved
                    DWORD          Offset;        // ignored
                    DWORD          OffsetHigh;         //
          ignored
                    WSAEVENT  hEvent;
               } WSAOVERLAPPED, LPWSAOVERLAPPED;
          
          If the lpCompletionRoutine parameter is NULL, the
          hEvent field of lpOverlapped must be an event
          object handle which is signaled when the
          overlapped operation completes. An application can
          use WSAWaitForMultipleEvents() or
          WSAGetOverlappedResult() to wait or poll on the
          event object.
          
          The lpCompletionRoutine must be non-NULL and the
          hEvent field is used to pass context information
          to the completion routine.
          
          The prototype of the completion routine is as
          follows:
          
               VOID CALLBACK CompletionRoutine( SOCKET s,
          DWORD dwError,      DWORD cbTransferred,
          LPWSAOVERLAPPED lpOverlapped );
          
          CompletionRoutine is a placeholder for an
          application-defined or library-defined function
          pointername. dwError specifies the completion
          status for the overlapped operation as indicated
          by lpOverlapped. cbTransferred specifies the
          number of bytes received. This function does not
          return a value.
          
          Returning from this function allows invocation of
          another pending completion routine for this
          socket. In Win32 environments, all waiting
          completion routines are called before the
          alterable thread's wait is satisfied with a return
          code of WSA_IO_COMPLETION. The completion routines
          may be called in any order, not necessarily in the
          same order the overlapped operations are
          completed. However, the posted buffers are
          guaranteed to be filled in the same order they are
          supplied
          
          lpFlags 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 lpFlags parameter.  The
          latter is constructed by or-ing any of the
          following values:

          Value     Meaning
          MSG_PEEK  Peek at the incoming data.  The data is
                    copied into the buffer but is not
                    removed from the input queue. {Hmmm,
                    "input queue" implies receive buffering
                    is occurring, which sort of defeats the
                    purpose of overlapped I/O.  Should this
                    be a valid flag for overlapped I/O?}
          
          MSG_OOB   Process out-of-band data (See section
                    for a discussion of this topic.)
          
          Upon the completion of the overlapped operation,
          the lpNumberOfBytesRecvd parameter is filled with
          the number of bytes received, and, for message-
          oriented sockets, the MSG_PARTIAL bit is set in
          the lpFlags parameter if a partial message is
          received. If a complete message is received,
          MSG_PARTIAL is cleared in lpFlags.


Return Value   If no error occurs, WSPRecvWSPrecv() returns
          the number of bytes received.  If the connection
          has been closed, it returns 0. Otherwise, a value
          of SOCKET_ERROR is returned, and a specific error
          code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAENOTCONN         The socket is not connected.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              WSACancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.

          WSAENETRESET        The connection must be reset
                              because the service provider
                              dropped it.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       MSG_OOB was specified, but the
                              socket is not stream style
                              such as type SOCK_STREAM, out-
                              of-band data is not supported
                              in the communication domain
                              associated with this socket,
                              or the socket is
                              unidirectional and supports
                              only send operations.
          
          WSAESHUTDOWN        The socket has been shutdown;
                              it is not possible to
                              WSPRecvWSPrecv() on a socket
                              after WSPShutdownWSPshutdown()
                              has been invoked with how set
                              to SD_RECEIVE or SD_BOTH.
          
          WSAEWOULDBLOCK      There are too many outstanding
                              overlapped I/O requests.
          
          WSAEMSGSIZE         The message was too large to
                              fit into the specified buffer
                              and was truncated. Any
                              trailing portion of the
                              message that did not fit into
                              the buffer has been discarded.
                               {Does this make sense?}
          
          WSAEINVAL           The socket has not been bound
                              with WSPBindWSPbind(), or the
                              socket is not created with the
                              overlapped flag.
          
          WSAECONNABORTED     The virtual circuit was
                              aborted due to timeout or
                              other failure.
          
          WSAECONNRESET       The virtual circuit was reset
                              by the remote side.

See Also  WSPSocket()
3.1.2.121 WSPRecvFromWSPrecvfrom()

Description    Receive a datagram and store the source
          address.

          #include <ws2spi.h>

          int WSPAPI WSPRecvFromWSPrecvfrom ( SOCKET s,
          LPVOID lpBuffer, DWORD nNumberOfBytesToRecv,
          LPDWORD lpNumberOfBytesRecvd, LPINT lpFlags,
          LPVOID lpFrom, LPINT lpFromlen, LPWSAOVERLAPPED
          lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE
          lpCompletionRoutine, int FAR * lpErrno );

          
          s               A descriptor identifying an
                         overlapped, connected socket. which
                         was created using WSPSocket() with
                         flag WSA_FLAG_OVERLAPPED.
          
          lpBuffer       A pointer to the buffer for the
                         incoming data.
          
          nNumberOfBytesToRecv     The number of bytes to
                         receive from the network.
          
          lpNumberOfBytesRecvd     A pointer to the number
                         of bytes received by this call.
          
          lpFlags        A pointer to flags.
          
          lpFrom         An optional pointer to a buffer
                         which will hold the source address
                         upon the completion of the
                         overlapped operation.
          
          lpFromlen      An optional pointer to the size of
                         the from buffer.
          
          lpOverlapped   A pointer to a WSAOVERLAPPED
                         structure.
          
          lpCompletionRoutine A pointer to the completion
                         routine called when the receive
                         operation has been completed.
          
          lpErrno        A pointer to the error code.

Remarks   This function is used to post a buffer into which
          incoming data will be placed as it becomes
          available on a (possibly connected) socket. For
          connectionless socket types, the address from
          which the data originated is copied to the buffer
          pointed by lpFrom. The value pointed to by
          lpFromlen is initialized to the size of this
          buffer, and is modified on return to indicate the
          actual size of the address stored there. The
          lpFrom and lpFromlen parameters are ignored for
          connection-oriented sockets.

          For non-overlapped socket, this function behaves
          like the standard recvfrom() API with identical
          blocking semantics. The lpOverlapped and
          lpCompletionRoutine parameters are ignored. The
          completion status of this SPI is the final
          completion status of the receive operation.
          
          For overlapped sockets, the final completion
          status is retrieved via the
          WSAGetOverlappedResult() API.

          For byte stream style sockets (e.g., type
          SOCK_STREAM), incoming data is placed into the
          buffer until the buffer is filled. For message-
          oriented sockets, an incoming message is placed
          into the supplied buffer, up to the size of the
          buffer supplied. If the message is larger than the
          buffer supplied, the buffer is filled with the
          first part of the message, the excess data is
          lost, and WSPRecvFromWSPrecvfrom()
          indicatesreturns the error code WSAEMSGSIZE.
          
          If no incoming data is available at the socket,
          the recvfrom() 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 select(),
          WSAAsyncSelect() or WSACallbackSelect() may be
          used to determine when more data arrives.
          
          If the socket is connection-oriented and the
          remote side has shut down the connection
          gracefully, a WSPRecvFromWSPrecvfrom() will
          complete immediately with 0 bytes received. If the
          connection has been reset WSPRecvFromWSPrecvfrom()
          will fail with the error WSAECONNRESET.
          
          This function may be called from within the
          completion routine of a previous WSPRecvWSPrecv(),
          WSPRecvFromWSPrecvfrom(), WSPSendWSPsend() or
          WSPSendToWSPsendto() function.
          
          When called with an overlapped socket, the
          lpOverlapped parameter much be valid for the
          duration of the overlapped operation. The
          WSAOVERLAPPED structure has the following form:
          
               typedef struct _WSAOVERLAPPED {
                    DWORD          Internal;      //
          reserved
                    DWORD          InternalHigh;  //
          reserved
                    DWORD          Offset;        // ignored
                    DWORD          OffsetHigh;         //
          ignored
                    WSAEVENT  hEvent;
               } WSAOVERLAPPED, LPWSAOVERLAPPED;
          
          If the lpCompletionRoutine parameter is NULL, the
          hEvent field of lpOverlapped must be an event
          object handle which is signaled when the
          overlapped operation completes. An application can
          use WSAWaitForMultipleEvents() or
          WSAGetOverlappedResult() to wait or poll on the
          event object.
          
          The lpCompletionRoutine must be non-NULL and the
          hEvent field is used to pass context information
          to the completion routine.
          
          The prototype of the completion routine is as
          follows:
          
               VOID CALLBACK CompletionRoutine( SOCKET s,
          DWORD dwError,      DWORD cbTransferred,
          LPWSAOVERLAPPED lpOverlapped );
          
          CompletionRoutine is a placeholder for an
          application-defined or library-defined function
          pointername. dwError specifies the completion
          status for the overlapped operation as indicated
          by lpOverlapped. cbTransferred specifies the
          number of bytes received. This function does not
          return a value.
          
          Returning from this function allows invocation of
          another pending completion routine for this
          socket. In Win32 environments, all waiting
          completion routines are called before the
          alterable thread's wait is satisfied with a return
          code of WSA_IO_COMPLETION. The completion routines
          may be called in any order, not necessarily in the
          same order the overlapped operations are
          completed. However, the posted buffers are
          guaranteed to be filled in the same order they are
          supplied
          
          Flags 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 flags parameter.  The latter is
          constructed by or-ing any of the following values:

          Value     Meaning
          MSG_PEEK  Peek at the incoming data.  The data is
                    copied into the buffer but is not
                    removed from the input queue.
          
          MSG_OOB   Process out-of-band data (See section
                    for a discussion of this topic.)
          
          Upon the completion of the overlapped operation,
          the lpNumberOfBytesRecvd parameter is filled with
          the number of bytes received, and, for message-
          oriented sockets, the MSG_PARTIAL bit is set in
          the lpFlags parameter if a partial message is
          received. If a complete message is received,
          MSG_PARTIAL is cleared in lpFlags.
          

Return Value   If no error occurs, WSPRecvFromWSPrecvfrom()
          returns the number of bytes received.  If the
          connection has been closed, it returns0.
          Otherwise, a value of SOCKET_ERROR is returned,
          and a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEFAULT           The lpFromlen argument was
                              invalid: the lpFrom buffer was
                              too small to accommodate the
                              peer address.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              WSACancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.

          WSAEINVAL           The socket has not been bound
                              with WSPBindWSPbind(), or the
                              socket is not created with the
                              overlapped flag.
          
          WSAENETRESET        The connection must be reset
                              because the Winsock provider
                              dropped it.
          
          WSAENOTCONN         The socket is not connected
                              (connection-oriented sockets
                              only).
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       MSG_OOB was specified, but the
                              socket is not stream style
                              such as type SOCK_STREAM, out-
                              of-band data is not supported
                              in the communication domain
                              associated with this socket,
                              or the socket is
                              unidirectional and supports
                              only send operations.
          
          WSAESHUTDOWN        The socket has been shutdown;
                              it is not possible to
                              WSPRecvFromWSPrecvfrom() on a
                              socket after shutdown() has
                              been invoked with how set to
                              SD_RECEIVE or SD_BOTH.
          
          WSAEWOULDBLOCK      There are too many outstanding
                              overlapped I/O requests.
          
          WSAEMSGSIZE         The message was too large to
                              fit into the specified buffer
                              and was truncated. Any
                              trailing portion of the
                              message that did not fit into
                              the buffer has been discarded.
                              {Does this make sense?}
          
          WSAECONNABORTED     The virtual circuit was
                              aborted due to timeout or
                              other failure.
          
          WSAECONNRESET       The virtual circuit was reset
                              by the remote side.
          
          
See Also  WSPSocket()

W3.1.2.212 WSPSendWSPsend()

Description    Send data on a connected socket.

          #include <ws2spi.h>

          int WSPAPI WSPSendWSPsend ( SOCKET s, LPVOID
          lpBuffer, DWORD nNumberOfBytesToSend, LPDWORD
          lpNumberOfBytesSent, int nFlags, LPWSAOVERLAPPED
          lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE
          lpCompletionRoutine, int FAR * lpErrno );

          
          s               A descriptor identifying an
                         overlapped, connected socket. which
                         was created using WSPSocket() with
                         flag WSA_FLAG_OVERLAPPED.
          
          lpBuffer       A pointer to the buffer for the
                         outgoing data.
          
          nNumberOfBytesToSend     The number of bytes to
                         send to the network.
          
          lpNumberOfBytesSent A pointer to the number of
                         bytes sent by this call.
          
          iFlags         Flags.
          
          lpOverlapped   A pointer to a WSAOVERLAPPED
                         structure.
          
          lpCompletionRoutine A pointer to the completion
                         routine called when the send
                         operation has been completed.
          
          lpErrno        A pointer to the error code.

Remarks   WSPSendWSPsend() is used to write outgoing data on
          an overlapped, connected socket asynchronously.
          For message-oriented sockets, it is an error care
          must be taken not to exceed the maximum packet
          size of the underlying transportprovider, which
          can be obtained by getting the value of socket
          option SO_MAX_DG_SIZE. If the data is too long to
          pass atomically through the underlying protocol
          the error WSAEMSGSIZE is returned, and no data is
          transmitted.

          Note that the successful completion of a
          WSPSendWSPsend() does not indicate that the data
          was successfully delivered.
          
          For non-overlapped socket, this function behaves
          like the standard send() API with identical
          blocking semantics. The lpOverlapped and
          lpCompletionRoutine parameters are ignored. The
          completion status of this SPI is the final
          completion status of the receive operation.
          
          For overlapped sockets, the final completion
          status is retrieved via the
          WSAGetOverlappedResult() API.

          If no buffer space is available within the
          transport system to hold the data to be
          transmitted, send() will block unless the socket
          has been placed in a non-blocking I/O mode.  On
          non-blocking stream-oriented 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
          select(), WSAAsyncSelect() or WSACallbackSelect()
          call may be used to determine when it is possible
          to send more data.
          
          This function may be called from within the
          completion routine of a previous WSPRecvWSPrecv(),
          WSPRecvFromWSPrecvfrom(), WSPSendWSPsend() or
          WSPSendToWSPsendto() function.
          
          When called with an overlapped socket, the
          lpOverlapped parameter much be valid for the
          duration of the overlapped operation. The
          WSAOVERLAPPED structure has the following form:
          
               typedef struct _WSAOVERLAPPED {
                    DWORD          Internal;      //
          reserved
                    DWORD          InternalHigh;  //
          reserved
                    DWORD          Offset;        // ignored
                    DWORD          OffsetHigh;         //
          ignored
                    WSAEVENT  hEvent;
               } WSAOVERLAPPED, LPWSAOVERLAPPED;
          
          If the lpCompletionRoutine parameter is NULL, the
          hEvent field of lpOverlapped must be an event
          object handle which is signaled when the
          overlapped operation completes. An application can
          use WSAWaitForMultipleEvents() or
          WSAGetOverlappedResult() to wait or poll on the
          event object.
          
          The lpCompletionRoutine must be non-NULL and the
          hEvent field is used to pass context information
          to the completion routine.
          
          The prototype of the completion routine is as
          follows:
          
               VOID CALLBACK CompletionRoutine( SOCKET s,
          DWORD dwError,      DWORD cbTransferred,
          LPWSAOVERLAPPED lpOverlapped );
          
          CompletionRoutine is a placeholder for an
          application-defined or library-defined function
          pointername. dwError specifies the completion
          status for the overlapped operation as indicated
          by lpOverlapped. cbTransferred specifies the
          number of bytes received. This function does not
          return a value.
          
          Returning from this function allows invocation of
          another pending completion routine for this
          socket. In Win32 environments, all waiting
          completion routines are called before the
          alterable thread's wait is satisfied with a return
          code of WSA_IO_COMPLETION. The completion routines
          may be called in any order, not necessarily in the
          same order the overlapped operations are
          completed. However, the posted buffers are
          guaranteed to be sent in the same order they are
          supplied
          
          Flags 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 flags parameter. The latter is
          constructed by or-ing any of the following values:

          Value     Meaning
          MSG_DONTROUTE
                    Specifies that the data should not be
                    subject to routing. A Winsock service
                    provider may choose to ignore this flag;
                    see also the discussion of the
                    SO_DONTROUTE option in section
                    2.8.42.8.42.8.4.
          
          MSG_OOB   Send out-of-band data (stream style
                    socket such as SOCK_STREAM only; see
                    also section)
          
          MSG_PARTIAL    Specifies that lpBuffer only
                    contains a partial message. Note that
                    this flag will be ignored by transports
                    which do not support partial message
                    transmissions.
          
          Upon the completion of the overlapped operation,
          the lpNumberOfBytesSent parameter is filled with
          the number of bytes sent.
          
          MSG_INTERRUPT
                    Specifies that this function is being
                    called in interrupt context.
          

Return Value   If no error occurs, WSPSendWSPsend() returns
          0. the total number of characters sent.  (Note
          that this may be less than the number indicated by
          len.) Otherwise, a value of SOCKET_ERROR is
          returned, and a specific error code is available
          in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEACCES           The requested address is a
                              broadcast address, but the
                              appropriate flag was not set.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              WSACancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.
          
          WSAEFAULT           The lpBuffer argument is not
                              in a valid part of the user
                              address space.
          
          WSAENETRESET        The connection must be reset
                              because the Winsock provider
                              dropped it.
          
          WSAENOBUFS          The Winsock provider reports a
                              buffer deadlock.
          
          WSAENOTCONN         The socket is not connected.
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       MSG_OOB was specified, but the
                              socket is not stream style
                              such as type SOCK_STREAM, out-
                              of-band data is not supported
                              in the communication domain
                              associated with this socket,
                              or the socket is
                              unidirectional and supports
                              only receive operations.
          
          WSAESHUTDOWN        The socket has been shutdown;
                              it is not possible to
                              WSPSendWSPsend() on a socket
                              after WSPShutdownWSPshutdown()
                              has been invoked with how set
                              to SD_SEND or SD_BOTH.
          
          WSAEWOULDBLOCK      There are too many outstanding
                              overlapped I/O requests.
          
          WSAEMSGSIZE         The socket is message-
                              oriented, and the message is
                              larger than the maximum
                              supported by the underlying
                              transport.
          
          WSAEINVAL           The socket has not been bound
                              with WSPBindWSPbind(), or the
                              socket is not created with the
                              overlapped flag.
          
          WSAECONNABORTED     The virtual circuit was
                              aborted due to timeout or
                              other failure.
          
          WSAECONNRESET       The virtual circuit was reset
                              by the remote side.
          

See Also  WSPSocket()

3.1.2.213 WSPSendToWSPsendto()

Description    Send data to a specific destination using
          overlapped I/O.

          #include <ws2spi.h>

          int WSPAPI WSPSendToWSPsendto ( SOCKET s, LPVOID
          lpBuffer, DWORD nNumberOfBytesToSend, LPDWORD
          lpNumberOfBytesSent, int nFlags, LPVOID lpTo, int
          nTolen, LPWSAOVERLAPPED lpOverlapped,
          LPWSAOVERLAPPED_COMPLETION_ROUTINE
          lpCompletionRoutine, int FAR * lpErrno );

          
          s               A descriptor identifying an
                         overlapped, connected socket which
                         was created using WSPSocket() with
                         flag WSA_FLAG_OVERLAPPED.
          
          lpBuffer       A pointer to the buffer for the
                         outgoing data.
          
          nNumberOfBytesToSend     The number of bytes to
                         send to the network.
          
          lpNumberOfBytesSent A pointer to the number of
                         bytes sent by this call.
          
          iFlags         Flags.
          
          lpTo           An optional pointer to the address
                         of the target socket.
          
          iTolen         The size of the address in lpTo.
          
          lpOverlapped   A pointer to a WSAOVERLAPPED
                         structure.
          
          lpCompletionRoutine A pointer to the completion
                         routine called when the send
                         operation has been completed.
          
          lpErrno        A pointer to the error code.

Remarks   WSPSendToWSPsendto() is used to write outgoing
          data on an overlapped socket asynchronously. For
          message-oriented sockets, it is an errorcare must
          be taken not to exceed the maximum packet size of
          the underlying transportsubnets, which can be
          obtained by getting the value of socket option
          SO_MAX_DG_SIZE. If the data is too long to pass
          atomically through the underlying protocol the
          error WSAEMSGSIZE is returned, and no data is
          transmitted.

          Note that the successful completion of a
          WSPSendToWSPsendto() does not indicate that the
          data was successfully delivered.
          
          For non-overlapped socket, this function behaves
          like the standard sendto() API with identical
          blocking semantics. The lpOverlapped and
          lpCompletionRoutine parameters are ignored. The
          completion status of this SPI is the final
          completion status of the receive operation.
          
          For overlapped sockets, the final completion
          status is retrieved via the
          WSAGetOverlappedResult() API.

          WSPSendToWSPsendto() is normally used on a
          connectionless socket to send a datagram to a
          specific peer socket identified by the lpTo
          parameter. On a connection-oriented socket, the
          lpTo and iTolen parameters are ignored; in this
          case the WSPSendToWSPsendto() is equivalent to
          WSPSendWSPsend().
          
          This function may be called from within the
          completion routine of a previous WSPRecvWSPrecv(),
          WSPRecvFromWSPrecvfrom(), WSPSendWSPsend() or
          WSPSendToWSPsendto() function.
          
          When called with an overlapped socket, the
          lpOverlapped parameter much be valid for the
          duration of the overlapped operation. The
          WSAOVERLAPPED structure has the following form:
          
               typedef struct _WSAOVERLAPPED {
                    DWORD          Internal;      //
          reserved
                    DWORD          InternalHigh;  //
          reserved
                    DWORD          Offset;        // ignored
                    DWORD          OffsetHigh;         //
          ignored
                    WSAEVENT  hEvent;
               } WSAOVERLAPPED, LPWSAOVERLAPPED;
          
          If the lpCompletionRoutine parameter is NULL, the
          hEvent field of lpOverlapped must be an event
          object handle which is signaled when the
          overlapped operation completes. An application can
          use WSAWaitForMultipleEvents() or
          WSAGetOverlappedResult() to wait or poll on the
          event object.
          
          The lpCompletionRoutine must be non-NULL and the
          hEvent field is used to pass context information
          to the completion routine.
          
          The prototype of the completion routine is as
          follows:
          
               VOID CALLBACK CompletionRoutine( SOCKET s,
          DWORD dwError,      DWORD cbTransferred,
          LPWSAOVERLAPPED lpOverlapped );
          
          CompletionRoutine is a placeholder for an
          application-defined or library-defined function
          pointername. dwError specifies the completion
          status for the overlapped operation as indicated
          by lpOverlapped. cbTransferred specifies the
          number of bytes received. This function does not
          return a value.
          
          Returning from this function allows invocation of
          another pending completion routine for this
          socket. In Win32 environments, all waiting
          completion routines are called before the
          alterable thread's wait is satisfied with a return
          code of WSA_IO_COMPLETION. The completion routines
          may be called in any order, not necessarily in the
          same order the overlapped operations are
          completed. However, the posted buffers are
          guaranteed to be sent in the same order they are
          supplied
          
          Flags 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 flags parameter. The latter is
          constructed by or-ing any of the following values:

          Value     Meaning
          MSG_DONTROUTE
                    Specifies that the data should not be
                    subject to routing. A WINSOCK service
                    provider may choose to ignore this flag;
                    see also the discussion of the
                    SO_DONTROUTE option in section
                    2.8.42.8.42.8.4.
          
          MSG_OOB   Send out-of-band data (stream style
                    socket such as SOCK_STREAM only; see
                    also section)
          
          MSG_PARTIAL    Specifies that lpBuffer only
                    contains a partial message. Note that
                    this flag will be ignored by transports
                    which do not support partial message
                    transmissions.
          
          Upon the completion of the overlapped operation,
          the lpNumberOfBytesSent parameter is filled with
          the number of bytes sent.
          

Return Value   If no error occurs, WSPSendToWSPsendto()
          returns 0. Otherwise, a value of SOCKET_ERROR is
          returned, and a specific error code is available
          in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEACCES           The requested address is a
                              broadcast address, but the
                              appropriate flag was not set.
          
          WSAEINTR            The (blocking) call was
                              canceled via
                              WSACancelBlockingCall().
          
          WSAEINPROGRESS      A blocking PII operation is in
                              progress.

          WSAEFAULT           The lpBuffer or lpTo
                              parameters are not part of the
                              user address space, or the
                              lpTo argument is too small
                              (less than the sizeof a struct
                              sockaddr).
          
          WSAENETRESET        The connection must be reset
                              because the Winsock provider
                              dropped it.
          
          WSAENOBUFS          The Winsock provider reports a
                              buffer deadlock.
          
          WSAENOTCONN         The socket is not connected
                              (connection-oriented sockets
                              only)
          
          WSAENOTSOCK         The descriptor is not a
                              socket.
          
          WSAEOPNOTSUPP       MSG_OOB was specified, but the
                              socket is not stream style
                              such as type SOCK_STREAM, out-
                              of-band data is not supported
                              in the communication domain
                              associated with this socket,
                              or the socket is
                              unidirectional and supports
                              only receive operations.
          
          WSAESHUTDOWN        The socket has been shutdown;
                              it is not possible to
                              WSPSendToWSPsendto() on a
                              socket after
                              WSPShutdownWSPshutdown() has
                              been invoked with how set to
                              SD_SEND or SD_BOTH.
          
          WSAEWOULDBLOCK      There are too many outstanding
                              overlapped I/O requests.
          
          WSAEMSGSIZE         The socket is message-
                              oriented, and the message is
                              larger than the maximum
                              supported by the underlying
                              transport.
          
          WSAEINVAL           The socket has not been bound
                              with WSPBindWSPbind(), or the
                              socket is not created with the
                              overlapped flag.
          
          WSAECONNABORTED     The virtual circuit was
                              aborted due to timeout or
                              other failure.
          
          WSAECONNRESET       The virtual circuit was reset
                              by the remote side.
          
          WSAEADDRNOTAVAIL    The specified address is not
                              available from the local
                              machine.
          
          WSAEAFNOSUPPORT     Addresses in the specified
                              family cannot be used with
                              this socket.
          
          WSAEDESTADDRREQ     A destination address is
                              required.
          
          WSAENETUNREACH      The network can't be reached
                              from this host at this time.
          
See Also  WSPSocket()
3.1.2.214 WSPSetBlockingHook32()

Description    Establish an application-specific blocking
          hook function.

          #include <ws2spi.h>

          LPBLOCKINGPRC WSPAPI WSPSetBlockingHook32 (
          LPBLOCKINGPROC lpBlockFunc, int FAR * lpErrno );
          
          lpBlockFunc    A pointer toot the procedure
                    instance address of the blocking
                    function to be installed.

          lpErrno   A pointer to the error code.

Remarks   This function is only applicable to the 32-bit
SPIis only available in the 32-bit SPI.
          
          This function installs a new function which the
          Winsock Service Provider should use to implement
          blocking socket function calls.
          
          Winsock Service Providers include a default
          mechanism by which blocking socket functions are
          implemented. The function WSPSetBlockingHook32()
          gives the application the ability to execute its
          own function at "blocking" time in place of the
          default function.
          
          When an application invokes a blocking Windows
          Sockets API operation, the Winsock Service
          Provider initiates the operation and then enters a
          loop which is similar to the following pseudocode:
          
          for(;;) {
               /* flush messages for good user response */
               while(BlockingHook())
                    ;
               /* check for WSPCancelBlockingCall32() */
               if(operation_cancelled())
                    break;
               /* check to see if operation completed */
               if(operation_complete())
                    break;     /* normal completion */
          }
          
          Note that Winsock Service Providers 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
          BlockingHook() function is equivalent to:
          
          BOOL DefaultBlockingHook(void) {
               MSG msg;
               BOOL ret;
               /* get the next message if any */
               ret =
          (BOOL)PeekMessage(&msg,NULL,0,0,PM_REMOVE);
               /* if we got one, process it */
               if (ret) {
                    TranslateMessage(&msg);
                    DispatchMessage(&msg);
               }
               /* TRUE if we got a message */
               return ret;
          }
          
          The WSPSetBlockingHook32() 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 not intended as a mechanism for
          performing general applications functions. In
          particular, the only Windows Sockets SPI function
          which may be issued from a custom blocking hook
          function is WSPCancelBlockingCall32(), which will
          cause the blocking loop to terminate.
          
          This function must be implemented on a per-thread
          basis for multithreaded versions of Windows such
          as Windows NT. It thus provides for a particular
          thread to replace the blocking mechanism without
          affecting other threads.
          
          In multithreaded versions of Windows, there is no
          default blocking hook--blocking calls block the
          thread that makes the call. However, an
          application may install a specific blocking hook
          by calling WSPSetBlockingHook32(). This allows
          easy portability of applications that depend on
          the blocking hook behavior.
          
Return Value   The return value is a pointer to the
          procedure-instance of the previously installed
          blocking function. The Winsock DLL should save
          this return value so that it can be restored if
          necessary. (If "nesting" is not important, the
          Winsock DLL may simply discard the value returned
          by WSPSetBlockingHook32() and eventually use
          WSPUnhookBlockingHook32() to restore the default
          mechanism.) If the operation fails, a NULL pointer
          is returned, and a specific error code is
          available in lpErrno.
          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          

Comments  Attempting to call PSCleanup() from within a
          blocking hook and then failing to check the return
          code is a common PII programming error.  If an
          application needs to quit while a blocking call is
          outstanding, the application must first cancel the
          blocking call with PSCancelBlockingCall() then
          issue the PSCleanup() call once control has been
          returned to the application.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The Windows Sockets
                              implementation has detected
                              that the network subsystem has
                              failed.
          
          WSAEINPROGRESS      A blocking Windows Sockets
                              operation is in progress.
WSANOTINITIALISED             A successful PSStartup() must
                              occur before using this SPI.
          
          
See Also  WSPCancelBlockingCall32(), WSPIsBlocking32(),
          WSPUnhookBlockingHook32()
3.1.2.215 WSPSocket()

Description    Create a socket which is bound to a specific
          transport service provider.

{ May be revised to use PROTOCOL_INFO as an input param in
          place of af, type, protocol parameters}

          #include <ws2spiinsock2.h>

          SOCKET WSPAPI WSPSocket ( int af, int type, int
          protocol, DWORD dwProviderId, int nFlags, int FAR
          * lpErrno );

          
          af        An address family specification. The
                    only format currently supported is
                    PF_INET, which is the ARPA Internet
                    address format.
          
          type      A type specification for the new socket.
          
          protocol  A particular protocol to be used with
                    the socket, or 0 if the caller does not
                    wish to specify a protocol.
          
          dwProviderId   An opaque value returned by the
                    WSAEnumProtocolsEnumProtocols() API that
                    identifies a unique service provider.
                    This information is useful to provider
                    implementations that present multiple
                    service provider appearances to Winsock.
          
          iFlags    The socket attribute specification.
          
          lpErrno   A pointer to the error code.

Remarks   WSPSocket() causes a socket descriptor and any
          related resources to be allocated and bound to the
          transport service provider specified by
          dwProviderId. If protocol is not specified (i.e.,
          equal to zero), the default for the specified
          socket type is used. However, the address family
          may be given as AF_UNSPEC (unspecified), in which
          case the protocol parameter must be specified. The
          protocol number to use is particular to the
          "communication domain'' in which communication is
          to take place.
          
          {The new name res stuff should obviate the need to
          enumerate the list of supported socket types here}
          
          The following type specifications may be supported
          (all sockets are bi-directional unless specified
          otherwise):
          
           Type                    Explanation
           SOCK_STREAM             Alias for
                                    SOCK_REL_STREAM.
           
           SOCK_DGRAM              Alias for
                                    SOCK_UNREL_DGRAM.
           
           SOCK_SEQPACKET          Alias for
                                    SOCK_REL_DSTREAM.
           
           SOCK_RAW                Raw socket.
           
           SOCK_REL_STREAM         Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, byte
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.  Uses TCP
                                    for the Internet
                                    address family.
           
           SOCK_REL_DSTREAM        Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, message
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.
           
           SOCK_UNREL_DSTREAM      Connection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, message
                                    streamwith an out-of-
                                    band data transmission
                                    mechanism.
           
           SOCK_REL_UNISEND_DSTREAMConnection-oriented,
                                    reliable, one-way (send
                                    only), unduplicated,
                                    sequenced, message
                                    stream. The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_REL_UNIRECV_DSTREA
                                    M.
           
           SOCK_REL_UNIRECV_DSTREAMConnection-oriented,
                                    reliable, one-way
                                    (receive only),
                                    unduplicated,
                                    sequenced, message
                                    stream.  The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_REL_UNISEND_DSTREA
                                    M.
           
           SOCK_UNREL_UNISEND_DSTREAM   Connection-
                                    oriented, unreliable,
                                    one-way (send only),
                                    unduplicated,
                                    sequenced, message
                                    stream. The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_UNREL_UNIRECV_DSTR
                                    EAM.
           
           SOCK_UNREL_UNIRECV_DSTREAM   Connection-
                                    oriented, unreliable,
                                    one-way (receive only),
                                    unduplicated,
                                    sequenced, message
                                    stream.  The matching
                                    socket at the remote
                                    side need to be of
                                    style
                                    SOCK_UNREL_UNISEND_DSTR
                                    EAM.
           
           SOCK_REL_DGRAM          Connectionless,
                                    reliable, datagram.
           
           SOCK_UNREL_DGRAM        Connectionless,
                                    unreliable, datagram.
           
           SOCK_REL_ISOCH_DSTREAM  Connection-oriented
                                    reliable, unduplicated,
                                    sequenced, isochronous,
                                    message streamwith an
                                    out-of-band data
                                    transmission mechanism.
           
           SOCK_UNREL_ISOCH_DSTREAMConnection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, isochronous,
                                    message streamwith an
                                    out-of-band data
                                    transmission mechanism.
           
           SOCK_UNREL_ISOCH_STREAM Connection-oriented
                                    unreliable,
                                    unduplicated,
                                    sequenced, isochronous,
                                    byte streamwith an out-
                                    of-band data
                                    transmission mechanism.
              
          The iFlags parameter may be used to specify the
          attributes of the socket by or-ing any of the
          following Flags:

          Flag      Meaning
          WSA_FLAG_OVERLAPPED
                    This flag causes an overlapped socket to
                    be created. Overlapped sockets must
                    utilize the overlapped I/O features of
                    the WSPSendWSPsend(),
                    WSPSendToWSPsendto(), WSPRecvWSPrecv(),
                    WSPRecvFromWSPrecvfrom() SPI for I/O
                    operations, and allows multiple of these
                    to be initiated and in progress
                    simultaneously. Overlapped sockets are
                    always non-blocking.
          
          Connection-oriented sockets such as SOCK_STREAM
          provide full-duplex connections, and must be in a
          connected state before any data may be sent or
          received on it. A connection to another socket is
          created with a connect() call. Once connected,
          data may be transferred using WSPSendWSPsend() and
          WSPRecvWSPrecv() calls. When a session has been
          completed, a WSPCloseSocketWSPclosesocket() must
          be performed. Out-of-band data may also be
          transmitted as described in send() and received as
          described in recv().
          
          The communications protocols used to implement a
          reliable, connection-oriented socket 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
          error code set to WSAETIMEDOUT.
          
          Connectionless, message-oriented sockets allow
          sending and receiving of datagrams to and from
          arbitrary peers using WSPSendToWSPsendto() and
          WSPRecvFromWSPrecvfrom(). If such a socket is
          connect()ed to a specific peer, datagrams may be
          send to that peer using WSPSendWSPsend() and may
          be received from (only) this peer using
          WSPRecvWSPrecv().


Return Value   If no error occurs, WSPSocket() returns a
          descriptor referencing the new socket. Otherwise,
          a value of INVALID_SOCKET is returned, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful WSPStartup() must
                              occur before using this SPI.
          
          WSAENETDOWN         The network subsystem has
                              failed.
          
          WSAEAFNOSUPPORT     The specified address family
                              is not supported.
          
          WSAEINPROGRESS      A blocking Winsock call is in
                              progress, or the service
                              provider is still processing a
                              callback function.
          
          WSAEMFILE           No more socket descriptors are
                              available.
          
          WSAENOBUFS          No buffer space is available.
                              The socket cannot be created.
          
          WSAEPROTONOSUPPORT  The specified protocol is not
                              supported.
          
          WSAEPROTOTYPE       The specified protocol is the
                              wrong type for this socket.
          
          WSAESOCKTNOSUPPORT  The specified socket type is
                              not supported in this address
                              family.

See Also  WSPAccept, WSPBindWSPbind(), WSPConnect(),
          WSPGetSockNameWSPgetsockname(),
          WSPGetSockOptWSPgetsockopt(),
          WSPSetSockOptWSPsetsockopt(),
          WSPListenWSPlisten(), WSPRecvWSPrecv(),
          WSARecvFrom(), WSASend(), WSASendToWSASentTo(),
          WSPShutdownWSPshutdown(),
          WSPIoctlSocketWSPioctlsocket().

3.1.2.216 WSPStartup()

Description

          #include <ws2spi.h>

          int WSPAPI WSPStartup ( WORD wVersionRequested,
          LPWSADATA lpWSAData );

          
          wVersionRequested   The highest version of Winsock
                         SPI support that the caller can
                         use. The high order byte specifies
                         the minor version (revision)
                         number; the low-order byte
                         specifies the major version number.
          
          lpWSAData      A pointer to the WSADATA data
                         structure that is to receive
                         details of the Winsock service
                         provider.

Remarks   This function MUST be the first Winsock SPI
          function called by the Winsock DLL. It allows the
          Winsock DLL to specify the version of Winsock SPI
          required and to retrieve details of the specific
          Winsock service provider implementation. The
          Winsock DLL may only issue further Winsock SPI
          functions after a successful WSPStartup()
          invocation.

          In order to support future Winsock service
          providers and the Winsock DLL which may have
          functionality differences from the current Winsock
          SPI, a negotiation takes place in WSPStartup().
          The caller of WSPStartup() (namely, the Winsock
          DLL) and the Winsock service provider 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
          WSPStartup(), the Winsock service provider
          examines the version requested by the Winsock DLL.
          If this version is higher than the lowest version
          supported by the service provider, the call
          succeeds and the service provider returns in
          wHighVersion the highest version it supports and
          in wVersion the minimum of its high version and
          wVersionRequested. The Winsock service provider
          then assumes that the Winsock DLL will use
          wVersion. If the wVersion field of the WSADATA
          structure is unacceptable to the caller, it should
          call WSPCleanup() and either search for another
          Winsock service provider or fail to initialize.
          
          This negotiation allows both a Winsock service
          provider and the Winsock DLL to support a range of
          Winsock versions. The Winsock DLL can successfully
          utilize a Winsock service provider if there is any
          overlap in the version ranges. The following chart
          gives examples of how WSPStartup() works in
          conjunction with different DLL and Winsock service
          provider (SP) versions:

          DLL     SP      wVersionR wVer  wHighV  End Result
          versio  Versio  equested  sion  ersion
          ns      ns
          1.1     1.1     1.1       1.1   1.1     use 1.1
          1.0     1.0     1.1       1.0   1.0     use 1.0
          1.1
1.0               1.0 1.1 1.0       1.0   1.1     use 1.0
          1.1     1.0     1.1       1.1   1.1     use 1.1
                  1.1
          1.1     1.0     1.1       1.0   1.0     DLL fails
          1.0     1.1     1.0       ---   ---     WSAVERNOTSUPPO
                                                  RTED
          1.0     1.0     1.1       1.1   1.1     use 1.1
          1.1     1.1
          1.1     1.1     2.0       1.1   1.1     use 1.1
          2.0
2.0               1.1     2.0       1.1   1.1     DLL fails
          
          The following code fragment demonstrates how a DLL
          which supports only version 1.1 of Winsock SPI
          makes a WSPStartup() call:
          
          WORD wVersionRequested;
          WSADATA WSAData;
          int err;
          
          wVersionRequested = MAKEWORD( 1, 1 );
          
          err = WSPStartup( wVersionRequested, &WSAData );
          if ( err != 0 ) {
              /* Tell the user that we couldn't find a
          useable */
              /* Winsock service provider.
          */
              return;
          }
          
          /* Confirm that the Winsock service provider
          supports 1.1.*/
          /* Note that if the service provider supports
          versions greater    */
          /* than 1.1 in addition to 1.1, it will still
          return */
          /* 1.1 in wVersion since that is the version we
          */
          /* requested.
          */
          
          if ( LOBYTE( WSAData.wVersion ) != 1 ||
                   HIBYTE( WSAData.wVersion ) != 1 ) {
              /* Tell the user that we couldn't find a
          useable */
              /* Winsock service provider.
          */
              WSPCleanup( );
              return;
          }
          
          /* The Winsock service provider is acceptable.
          Proceed. */
          
          And this code fragment demonstrates how a Winsock
          service provider which supports only version 1.1
          performs the WSPStartup() negotiation:
          
          /* Make sure that the version requested is >= 1.1.
          */
          /* The low byte is the major version and the high
          */
          /* byte is the minor version.
          */
          
          if ( LOBYTE( wVersionRequested ) < 1 ||
               ( LOBYTE( wVersionRequested ) == 1 &&
                 HIBYTE( wVersionRequested ) < 1 ) {
              return WSAVERNOTSUPPORTED;
          }
          
          /* Since we only support 1.1, set both wVersion
          and  */
          /* wHighVersion to 1.1.
          */
          
          lpWSAData->wVersion = MAKEWORD( 1, 1 );
          lpWSAData->wHighVersion = MAKEWORD( 1, 1 );
          
          Once the Winsock DLL has made a successful
          WSPStartup() call, it may proceed to make other
          Winsock SPI calls as needed. When it has finished
          using the services of the Winsock service
          provider, the Winsock DLL must call WSPCleanup()
          in order to allow the Winsock service provider to
          free any resources for the Winsock DLL.

          Details of the actual Winsock service provider are
          described in the WSAData structure defined as
          follows:
          
          {If we remove iMaxSockets & iMaxUdpDg, should we
          rename the structure to WSAData2 to avoid
          confusion with the Winsock 1.1 WSAData?}
          
          struct WSAData {
               WORD           wVersion;
               WORD           wHighVersion;
               char
          szDescription[WSADESCRIPTION_LEN+1];
               char
          szSystemStatus[WSASYSSTATUS_LEN+1];
               unsigned short iMaxSockets;
               unsigned short iMaxUdpDg;
               char FAR *          lpVendorInfo;
          };
          
          The members of this structure are:
          Element   Usage
          wVersion  The version of the Winsock SPI
                    specification that the Winsock service
                    provider expects the caller to use.
          wHighVersion   The highest version of the Winsock
                    SPI specification that this service
                    provider can support (also encoded as
                    above). Normally this will be the same
                    as wVersion.
          szDescription  A null-terminated ASCII string into
                    which the Winsock DLL copies a
                    description of the Winsock service
                    provider. The text (up to 256 characters
                    in length) may contain any characters
                    except 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.
          szSystemStatus A null-terminated ASCII string into
                    which the Winsock service provider
                    copies relevant status or configuration
                    information. The Winsock service
                    provider 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.
          iMaxSockets    The maximum number of sockets which
                    a single process can potentially open. A
                    Winsock service provider may provide a
                    global pool of sockets for allocation to
                    any process; alternatively it may
                    allocate per-process resources for
                    sockets. The number may well reflect the
                    way in which the Winsock service
                    provider or the networking software was
                    configured. Application writers may use
                    this number as a crude indication of
                    whether the Winsock service provider is
                    usable by the application. For example,
                    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 might be used.)
                    Obviously there is no guarantee that a
                    particular application can actually
                    allocate iMaxSockets sockets, since
                    there may be other Winsock applications
                    in use.
          iMaxUdpDg This value is retained for compatibility
                    with Windows Sockets specification 1.1,
                    but should not be used when developing
                    new applications. The value supplied
                    here will always be 512, the minimum
                    allowed. For the actual maximum message
                    size specific to a particular Winsock
                    service provider and socket type, the
                    Winsock DLL should use
                    WSPGetSockOptWSPgetsockopt() to retrieve
                    the value of option SO_MAX_DG_SIZE after
                    a socket has been created. The minimum
                    value of iMaxUdpDg for a compliant PII
                    implementation is 512.  Note that
                    regardless of the value of iMaxUdpDg, it
                    is inadvisable to attempt to send a
                    broadcast datagram which is larger than
                    the Maximum Transmission Unit (MTU) for
                    the network.  (The PII  does not provide
                    a mechanism to discover the MTU, but it
                    must be no less than 512 bytes.)
          lpVendorInfo   This value should be ignored. It is
                    retained for compatibility with Windows
                    Sockets specification 1.1. The Winsock
                    DLL needing to access vendor-specific
                    configuration information should use
                    WSPGetSockOptWSPgetsockopt() to retrieve
                    the value of option PVD_CONFIG. The
                    definition of this value (if utilized)
                    is beyond the scope of this
                    specification.
          
          A PII.DLL may call PSStartup() more than once if
          it needs to obtain the WSAData structure
          information more than once.  However, the
          wVersionRequired parameter is assumed to be the
          same on all calls to PSStartup(); that is, a
          PII.DLL cannot change the version of PII SPI it
          expects after the initial call to PSStartup().
          
          There must be one PSCleanup() call corresponding
          to every PSStartup() call to allow third-party
          DLLs to make use of a PII.DLL on behalf of an
          application.  This means, for example, that if an
          application calls PSStartup() three times, it must
          call PSCleanup() three times.  The first two calls
          to PSCleanup() do nothing except decrement an
          internal counter; the final PSCleanup() call for
          the task does all necessary resource deallocation
          for the task.


Return Value   WSPStartup() returns zero if successful.
          Otherwise it returns one of the error codes listed
          below. Note that the normal mechanism whereby the
          application calls PSGetLastError() to determine
          the error code cannot be used, since the PII.DLL
          may not have established the client data area
          where the "last error" information is stored.

Notes For
Winsock Service
Providers The Winsock DLL will make one and only one
          WSPStartup() call before issuing any other Winsock
          SPI calls for each Winsock service provider. This
          function can thus be utilized for initialization
          purposes.
          
          Further issues are discussed in the notes for
          WSPCleanup().

Error Codes                   WSASYSNOTREADY Indicates that
                              the underlying network
                              subsystem is not ready for
                              network communication.

          WSAVERNOTSUPPORTED  The version of Winsock SPI
                              support requested is not
                              provided by this particular
                              Winsock service provider.
          
          WSAEFAULT           The lpWSAData parameter is
                              invalid.
          
          WSAEINVAL           The PII version specified by
                              the application is not
                              supported by this DLL.

See Also  WSPSendWSPsend(), WSPSendToWSPsendto(),
          WSPCleanup()
3.1.2.217 WSPUnhookBlockingHook32()

Description    Restores the default blocking hook function.

          #include <ws2spi.h>

          int WSPAPI WSPUnhookBlockingHook32 ( int FAR *
          lpErrno );
          
          lpErrno   A pointer to the error code.

Remarks   This function is only applicable to the 32-bit
SPIis only available in the 32-bit SPI.
          
          This function removes any previous blocking hook
          that has been installed and reinstalls the default
          blocking mechanism.
          
          This function is only applicable to the 32-bit
          SPIis only available in the 32-bit SPI.
          
          WSPUnhookBlockingHook32() will always install the
          default mechanism, not the previous mechanism. If
          the Winsock DLL wishes 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 WSPSetBlockingHook32()) - it must save and
          restore the value returned by
          WSPSetBlockingHook32(); it cannot use
          WSPUnhookBlockingHook32().
          
          In multithreaded versions of Windows such as
          Windows NT, there is no default blocking hook.
          Calling WSPUnhookBlockingHook32() disables any
          blocking hook installed by the application and any
          blocking calls made block the thread which made
          the call.

Return Value   The return value is 0 if the operation has
          been successfully initiated. Otherwise the value
          SOCKET_ERROR is returned, and a specific error
          number is available in lpErrno.
          On a blocking socket, the return value indicates
          success or failure of the connection attempt.
          

Comments  Attempting to call PSCleanup() from within a
          blocking hook and then failing to check the return
          code is a common PII programming error.  If an
          application needs to quit while a blocking call is
          outstanding, the application must first cancel the
          blocking call with PSCancelBlockingCall() then
          issue the PSCleanup() call once control has been
          returned to the application.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSANOTINITIALISED   A successful WSPStartup() must
                              occur before using this SPI.
          
See Also  WSPCancelBlockingCall32(), WSPIsBlocking32(),
          WSPSetBlockingHook32()
4. Upcalls

This section contains the private "upcalls" that service
providers may make into the Windows Sockets DLL. All upcalls
are prefixed with "Xxx" to distinguish them from the normal
API and SPI entrypoints.
4.1 WPUXxxCreateSocketHandle()

Description    Creates a new socket handle.

          #include <ws2spi.h>

          SOCKET WSPAPI WPUXxxCreateSocketHandle ( DWORD
          dwProviderId, LPVOID lpContext, int FAR * lpErrno
          );

          dwProviderId   Identifies the calling service
                    provider. {We must provide a mechanism
                    for getting this to the provider,
                    perhaps at WspStartup() time?}
          
          lpContext A context value to associate with the
                    new socket handle.
          
          lpErrno   A pointer to the error code.

Remarks   This routine creates a new socket handle for the
          specified provider. The handle returned is Winsock
          specific; it is not a proper system handle.
          
          This routine is only used by providers that do not
          provide real system handles.

Return Value   If no error occurs,
          WPUXxxCreateSocketHandle() returns the new socket
          handle. Otherwise, it returns INVALID_SOCKET, and
          a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENOBUFS          Not enough buffers available,
                              too many sockets.

See Also  WPUXxxCloseSocketHandle()PSCancelBlockingCall().
4.2 WPUXxxCloseSocketHandle()

Description    Closes an existing socket handle.

          #include <ws2spi.h>

          int WSPAPI WPUXxxCloseSocketHandle ( SOCKET s, int
          FAR * lpErrno );

          s          Identifies a socket handle created with
                    WPUXxxCreateSocketHandle().
          
          lpErrno   A pointer to the error code.

Remarks   This routine closes an existing socket handle.
          This function removes the socket from Winsock's
          internal socket table. The owning service provider
          is responsible for releasing any resources
          associated with the socket.

Return Value   If no error occurs,
          WPUXxxCreateSocketHandle() returns 0. Otherwise,
          it returns SOCKET_ERROR, and a specific error code
          is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENOTSOCK         The descriptor is not a socket
                              created by
                              WPUXxxCreateSocketHandle().

See Also  WPUXxxCreateSocketHandle()PSCancelBlockingCall().
4.3 WPUXxxQuerySocketHandleContext()

Description    Queries the context value associated with the
          specified socket handle.

          #include <ws2spi.h>

          int WSPAPI WPUXxxQuerySocketHandleContext ( SOCKET
          s, LPVOID FAR * lpContext, int FAR * lpErrno );

          s          Identifies the socket whose context is
                    to be queried.
          
          lpContext A pointer to an LPVOID that will receive
                    the context value.
          
          lpErrno   A pointer to the error code.

Remarks   This routine queries the current context value
          associated with the specified socket handle.
          Service providers typically use this function to
          retrieve a pointer to provider-specific data
          associated with the socket. For example, a service
          provider may use the socket context to store a
          pointer to a structure containing the socket's
          state, local and remote transport addresses, event
          objects for signaling network events, etc.

Return Value   If no error occurs,
          WPUXxxQuerySocketHandleContext() returns 0 and
          stores the current context value in lpContext.
          Otherwise, it returns SOCKET_ERROR, and a specific
          error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENOTSOCK         The descriptor is not a socket
                              created by
                              WPUXxxCreateSocketHandle().

See Also  WPUXxxCreateSocketHandle(),
          WPUXxxSetSocketHandleContext()PSCancelBlockingCall
          ().
4.4 WPUXxxSetSocketHandleContext()

Description    Sets the context value associated with the
          specified socket handle.

          #include <ws2spi.h>

          int WSPAPI WPUXxxSetSocketHandleContext ( SOCKET
          s, LPVOID lpContext, int FAR * lpErrno );

          s          Identifies the socket whose context is
                    to be set.
          
          lpContext The new context value to associate with
                    the socket.
          
          lpErrno   A pointer to the error code.

Remarks   This routine sets the current context value
          associated with the specified socket handle.

Return Value   If no error occurs,
          WPUXxxSetSocketHandleContext() returns 0 and
          stores lpContext and the socket's new context
          value. Otherwise, it returns SOCKET_ERROR, and a
          specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          WSAENOTSOCK         The descriptor is not a socket
                              created by
                              WPUXxxCreateSocketHandle().

See Also  WPUXxxCreateSocketHandle(),
          WPUXxxQuerySocketHandleContext()PSCancelBlockingCa
          ll().
4.5 WPUXxxQueueUserAPC32()

Description    Queues a user-mode APC against the specified
          thread.

          #include <ws2spi.h>

          int WSPAPI WPUXxxQueueUserAPC32UserAPC ( DWORD
          dwThreadId, LPWSAUSERAPC lpfnUserApc, DWORD
          dwContext, int FAR * lpErrno );
          
          dwThreadId     Identifies the target thread for
                    the APC. This is typically a value
                    returned by the
                    WPUXxxGetCurrentThreadId() upcall.
          
          lpfnUserApc    Points to the function to be called
                    as a user-mode APC.
          
          dwContext A context value to be passed in to the
                    user-mode APC function.
          
          lpErrno   A pointer to the error code.

Remarks   This routine queues a user-mode APC against the
          specified thread. The APC will only execute when
          the specified thread is blocked in an alertable
          wait. This function is only available in 32 bit
          versions of the Winsock 2 DLL.
          
          LPWSAUSERAPC is defined as follows:
          
               typedef VOID (FAR * LPWSAUSERAPC)( DWORD
               dwContext );

Return Value   If no error occurs,
          WPUXxxQueueUserAPC32UserAPC() returns 0 and queues
          the APC for the specified thread. Otherwise, it
          returns SOCKET_ERROR, and a specific error code is
          available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          ????                dwThreadId does not specify a
                              valid thread.
          
See Also  WPUXxxGetCurrentThreadId32()PSCancelBlockingCall()
          .
4.6 WPUXxxGetCurrentThreadId32()

Description    Returns an operating-system specific
          identifier for the current thread.

          #include <ws2spi.h>

          DWORD WSPAPI WPUXxxGetCurrentThreadId32 ( VOID );

Remarks   This routine returns an operating-system specific
          identifier for the current thread. The returned
          value is suitable for use in the
          WPUXxxQueueUserAPC32UserAPC() upcall.
          
Return Value   WPUXxxGetCurrentThreadId32() returns the
          current thread ID.

See Also  WPUXxxQueueUserAPC32UserAPC()PSCancelBlockingCall(
          ).
5. Installation APIs

This section is super preliminary. These APIs will be
receive additional attention after the December 12th
meeting.

5.1 WPUInstallProvider()

Description    Installs the specified provider into the
          system configuration database.

          #include <ws2spi.h>

          int WSPAPI WPUInstallProvider( const char FAR *
          lpszProviderName, const char FAR *
          lpszProviderDllPath, const PROTOCOL_INFO FAR *
          lpProtocolInfoList, DWORD dwNumberOfEntries, DWORD
          FAR * lpdwProviderId, int FAR * lpErrno );

          lpszProviderName    Points to locally unique name
                         for this provider. This name must
                         not conflict with any currently
                         installed provider.
          
          lpszProviderDllPath Points to a fully qualified
                         path to the provider's DLL image.
                         The Winsock DLL passes this path
                         into the LoadLibrary API to load
                         the provider.
          
          lpProtocolInfoList  Points to an array of
                         PROTOCOL_INFO structures. Each
                         structure defines a
                         protocol/address_family/socket_type
                         supported by the provider.
          
          dwNumberOfEntries   Contains the number of entries
                         in the lpProtocolInfoList array.
          
          lpdwProviderId Points to a DWORD that will receive
                         the locally unique identifier for
                         the newly installed provider.
          
          lpErrno        A pointer to the error code.
          
Remarks   This routine creates the necessary common Winsock
          2 configuration information for the specified
          provider. After this routine completes
          successfully, the protocol information provided in
          lpProtocolInfoList will be returned by the
          WSAEnumProtocols API.
          
          Any file installation or service provider specific
          configuration information must be performed by the
          provider setup application.
          
Return Value   If no error occurs, WPUInstallProvider()
          returns 0. Otherwise, it returns SOCKET_ERROR, and
          a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          ????                ????
          
See Also  WPUDeinstallProvider(),
          WSAEnumProtocols()PSCancelBlockingCall().
5.2 WPUDeinstallProvider()

Description    Removes the specified provider from the
          system configuration database.

          #include <ws2spi.h>

          int WSPAPI WPUDeinstallProvider( DWORD
          dwProviderId, int FAR * lpErrno );

          dwProviderId   The locally unique identifier of
                         the provider to deinstall. This
                         must be a value previously returned
                         by WPUInstallProvider().
          
          lpErrno        A pointer to the error code.
          
Remarks   This routine removes the common Winsock 2
          configuration information for the specified
          provider. After this routine completes
          successfully, the protocol information associated
          with the provider will not be returned by the
          WSAEnumProtocols API.
          
          Any file removal or service provider specific
          configuration information removal must be
          performed by the provider setup application.
          
Return Value   If no error occurs, WPUDeinstallProvider()
          returns 0. Otherwise, it returns SOCKET_ERROR, and
          a specific error code is available in lpErrno.

Error Codes                   WSANOTINITIALISED   A
                              successful PSStartup() must
                              occur before using this SPI.
          
          ????                ????
          
See Also  WPUInstallProvider(),
          WSAEnumProtocols()PSCancelBlockingCall().
Appendix A. Error Codes and Header Files
A.1 Error Codes
The following is a list of possible error codes available in
the lpErrno parameter of each function, along with their
explanations. The error numbers are consistently set across
all Winsock-compliant implementations.

Winsock code   Berkeley       Err  Interpretation
               equivalent     or
WSAEINTR       EINTR          100  As in standard C
                              04
WSAEBADF       EBADF          100  As in standard C
                              09
WSAEACCES      EACCES         100  As in standard C
                              13
WSAEFAULT      EFAULT         100  As in standard C
                              14
WSAEINVAL      EINVAL         100  As in standard C
                              22
WSAEMFILE      EMFILE         100  As in standard C
                              24
WSAEWOULDBLOC  EWOULDBLOCK    100  As in BSD
K                             35
WSAEINPROGRES  EINPROGRESS    100  This error is returned
S                             36   if any
                                   Winsock function is
                                   called while a blocking
                                   function is
                                   in progress.
WSAEALREADY    EALREADY       100  As in BSD
                              37
WSAENOTSOCK    ENOTSOCK       100  As in BSD
                              38
WSAEDESTADDRR  EDESTADDRREQ   100  As in BSD
EQ                            39
WSAEMSGSIZE    EMSGSIZE       100  As in BSD
                              40
WSAEPROTOTYPE  EPROTOTYPE     100  As in BSD
                              41
WSAENOPROTOOP  ENOPROTOOPT    100  As in BSD
T                             42
WSAEPROTONOSU  EPROTONOSUPPO  100  As in BSD
PPORT          RT             43
WSAESOCKTNOSU  ESOCKTNOSUPPO  100  As in BSD
PPORT          RT             44
WSAEOPNOTSUPP  EOPNOTSUPP     100  As in BSD
                              45
WSAEPFNOSUPPO  EPFNOSUPPORT   100  As in BSD
RT                            46
WSAEAFNOSUPPO  EAFNOSUPPORT   100  As in BSD
RT                            47
WSAEADDRINUSE  EADDRINUSE     100  As in BSD
                              48
WSAEADDRNOTAV  EADDRNOTAVAIL  100  As in BSD
AIL                           49
WSAENETDOWN    ENETDOWN       100  As in BSD.  This error
                              50   may be reported at any
                                   time if the Winsock
                                   service provider
                                   detects an underlying
                                   failure.
WSAENETUNREAC  ENETUNREACH    100  As in BSD
H                             51
WSAENETRESET   ENETRESET      100  As in BSD
                              52
WSAECONNABORT  ECONNABORTED   100  As in BSD
ED                            53
WSAECONNRESET  ECONNRESET     100  As in BSD
                              54
WSAENOBUFS     ENOBUFS        100  As in BSD
                              55
WSAEISCONN     EISCONN        100  As in BSD
                              56
WSAENOTCONN    ENOTCONN       100  As in BSD
                              57
WSAESHUTDOWN   ESHUTDOWN      100  As in BSD
                              58
WSAETOOMANYRE  ETOOMANYREFS   100  As in BSD
FS                            59
WSAETIMEDOUT   ETIMEDOUT      100  As in BSD
                              60
WSAECONNREFUS  ECONNREFUSED   100  As in BSD
ED                            61
WSAELOOP       ELOOP          100  As in BSD
                              62
WSAENAMETOOLO  ENAMETOOLONG   100  As in BSD
NG                            63
WSAEHOSTDOWN   EHOSTDOWN      100  As in BSD
                              64
WSAEHOSTUNREA  EHOSTUNREACH   100  As in BSD
CH                            65
WSASYSNOTREAD                 100  Returned by
Y                             91   WSPStartup()
                                   indicating that the
                                   network subsystem is
                                   unusable.
WSAVERNOTSUPP                 100  Returned by
ORTED                         92   WSPStartup()
                                   indicating that the
                                   Winsock
                                   service provider cannot
                                   support the Winsock
                                   DLL.
WSANOTINITIAL                 100  Returned by any
ISED                          93   function except
                                   PSStartup() indicating
                                   that a successful
                                   PSStartup() has not yet
                                   been performed.

WSAHOST_NOT_F  HOST_NOT_FOUN  110  As in BSD.
OUND           D              01
WSATRY_AGAIN   TRY_AGAIN      110  As in BSD
                              02
WSANO_RECOVER  NO_RECOVERY    110  As in BSD
Y                             03
WSANO_DATA     NO_DATA        110  As in BSD
                              04


The first set of definitions is present to resolve
contentions between standard C error codes which may be
defined inconsistently between various C compilers.

The second set of definitions provides Winsock versions of
regular Berkeley Sockets error codes.

The third set of definitions consists of extended Winsock-
specific error codes.

The error numbers are derived from the ws2spi.h header file
listed in section A.2A.2A.2, and are based on the fact that
Winsock error numbers are computed by adding 10000 to the
"normal" Berkeley error number.

Note that this table does not include all of the error codes
defined in ws2spi.h. This is because it includes only errors
which might reasonably be returned by a Winsock service
provider: ws2spi.h, on the other hand, includes a full set
of BSD definitions to ensure compatibility with ported
software.


A.2 Header Files
A.2.1 Berkeley Header Files
A PII service provider who provides a development kit to
support the development of PII applications must supply a
set of vestigial 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:

#ifndef _PIISPI_
#include <PIISPI.h>
#endif

The header files provided for compatibility are:
netdb.h
arpa/inet.h
sys/time.h
sys/socket.h
netinet/in.h

The file PIISPI.h contains all of the type and structure
definitions, constants, macros, and function prototypes used
by the PII specification.  An application writer may choose
to ignore the compatibility headers and include PIISPI.h in
each source file.



A.2 Winsock SPI Header File - ws2spi.h

The ws2spi.h header file includes a number of types and
definitions from the standard Windows header file windows.h.
The windows.h in the Windows 3.0 SDK (Software Developer's
Kit) lacks a #include guard, so if you need to include
windows.h as well as ws2spi.h, you should define the symbol
_INC_WINDOWS before #including ws2spi.h, as follows:
          #include <windows.h>
          #define _INC_WINDOWS
          #include <ws2spi.h>
Users of the SDK for Windows 3.1 and later need not do this.

A Winsock service provider vendor MUST NOT make any
modifications to this header file which could impact binary
compatibility of Winsock applications. The constant values,
function parameters and return codes, and the like must
remain consistent across all Winsock service provider
vendors.


/* WS2SPI.H--definitions to be used with the Winsock service
provider.
 *
 * This header file corresponds to version 2.0 of the
Winsock SPI specification.
 *
 * This file includes parts which are Copyright (c) 1982-
1986 Regents
 * of the University of California.  All rights reserved.
The
 * Berkeley Software License Agreement specifies the terms
and
 * conditions for redistribution.
 */

#ifndef _WS2SPI_
#define _WS2SPI_

#ifndef _WS2API_

/*
 * Pull in WINDOWS.H if necessary
 */
#ifndef _INC_WINDOWS
#include <windows.h>
#endif /* _INC_WINDOWS */

/*
 * SPI function linkage.
 */

#define WSPAPI WSPAPI

/*
 * Basic system type definitions, taken from the BSD file
sys/types.h.
 */
typedef unsigned char   u_char;
typedef unsigned short  u_short;
typedef unsigned int    u_int;
typedef unsigned long   u_long;

/*
 * The new type to be used in all
 * instances which refer to sockets.
 */
typedef u_int           SOCKET;

/*
 * Select uses arrays of SOCKETs.  These macros manipulate
such
 * arrays.  FD_SETSIZE may be defined by the user before
including
 * this file, but the default here should be >= 64.
 *
 * CAVEAT IMPLEMENTOR and USER: THESE MACROS AND TYPES MUST
BE
 * INCLUDED IN WS2SPI.H EXACTLY AS SHOWN HERE.
 */
#ifndef FD_SETSIZE
#define FD_SETSIZE      64
#endif /* FD_SETSIZE */

typedef struct fd_set {
        u_short fd_count;               /* how many are SET?
*/
        SOCKET  fd_array[FD_SETSIZE];   /* an array of
SOCKETs */
} fd_set;

#ifdef __cplusplus
extern "C" {
#endif

extern int WSPAPI __WSAFDIsSet(SOCKET, fd_set FAR *);

#ifdef __cplusplus
}
#endif

#define FD_CLR(fd, set) do { \
    u_int __i; \
    for (__i = 0; __i < ((fd_set FAR *)(set))->fd_count ;
__i++) { \
        if (((fd_set FAR *)(set))->fd_array[__i] == fd) { \
            while (__i < ((fd_set FAR *)(set))->fd_count-1)
{ \
                ((fd_set FAR *)(set))->fd_array[__i] = \
                    ((fd_set FAR *)(set))->fd_array[__i+1];
\
                __i++; \
            } \
            ((fd_set FAR *)(set))->fd_count--; \
            break; \
        } \
    } \
} while(0)

#define FD_SET(fd, set) do { \
    if (((fd_set FAR *)(set))->fd_count < FD_SETSIZE) \
        ((fd_set FAR *)(set))->fd_array[((fd_set FAR
*)(set))->fd_count++]=fd;\
} while(0)

#define FD_ZERO(set) (((fd_set FAR *)(set))->fd_count=0)

#define FD_ISSET(fd, set) __WSAFDIsSet((SOCKET)fd, (fd_set
FAR *)set)

/*
 * Structure used in select() call, taken from the BSD file
sys/time.h.
 */
struct timeval {
        long    tv_sec;         /* seconds */
        long    tv_usec;        /* and microseconds */
};

/*
 * Operations on timevals.
 *
 * NB: timercmp does not work for >= or <=.
 */
#define timerisset(tvp)         ((tvp)->tv_sec || (tvp)-
>tv_usec)
#define timercmp(tvp, uvp, cmp) \
        ((tvp)->tv_sec cmp (uvp)->tv_sec || \
         (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec
cmp (uvp)->tv_usec)
#define timerclear(tvp)         (tvp)->tv_sec = (tvp)-
>tv_usec = 0

/*
 * Winsock extension
 */
#define MAKEWORD(low, high) ((WORD)(((BYTE)(low)) |
(((WORD)((BYTE)(high))) << 8)))

/*
 * Commands for ioctlsocket(),  taken from the BSD file
fcntl.h.
 *
 *
 * Ioctl's have the command encoded in the lower word,
 * and the size of any in or out parameters in the upper
 * word.  The high 2 bits of the upper word are used
 * to encode the in/out status of the parameter; for now
 * we restrict parameters to at most 128 bytes.
 */
#define IOCPARM_MASK    0x7f            /* parameters must
be < 128 bytes */
#define IOC_VOID        0x20000000      /* no parameters */
#define IOC_OUT         0x40000000      /* copy out
parameters */
#define IOC_IN          0x80000000      /* copy in
parameters */
#define IOC_INOUT       (IOC_IN|IOC_OUT)
                                        /* 0x20000000
distinguishes new &
                                           old ioctl's */
#define _IO(x,y)        (IOC_VOID|(x<<8)|y)

#define _IOR(x,y,t)
(IOC_OUT|(((long)sizeof(t)&IOCPARM_MASK)<<16)|(x<<8)|y)

#define _IOW(x,y,t)
(IOC_IN|(((long)sizeof(t)&IOCPARM_MASK)<<16)|(x<<8)|y)

#define FIONREAD    _IOR('f', 127, u_long) /* get # bytes to
read */
#define FIONBIO     _IOW('f', 126, u_long) /* set/clear non-
blocking i/o */
#define FIOASYNC    _IOW('f', 125, u_long) /* set/clear
async i/o */

/* Socket I/O Controls */
#define SIOCSHIWAT  _IOW('s',  0, u_long)  /* set high
watermark */
#define SIOCGHIWAT  _IOR('s',  1, u_long)  /* get high
watermark */
#define SIOCSLOWAT  _IOW('s',  2, u_long)  /* set low
watermark */
#define SIOCGLOWAT  _IOR('s',  3, u_long)  /* get low
watermark */
#define SIOCATMARK  _IOR('s',  7, u_long)  /* at oob mark?
*/

/*
 * Structures returned by network data base library, taken
from the
 * BSD file netdb.h.  All addresses are supplied in host
order, and
 * returned in network order (suitable for use in system
calls).
 */

struct  hostent {
        char    FAR * h_name;           /* official name of
host */
        char    FAR * FAR * h_aliases;  /* alias list */
        short   h_addrtype;             /* host address type
*/
        short   h_length;               /* length of address
*/
        char    FAR * FAR * h_addr_list; /* list of
addresses */
#define h_addr  h_addr_list[0]          /* address, for
backward compat */
};

/*
 * It is assumed here that a network number
 * fits in 32 bits.
 */
struct  netent {
        char    FAR * n_name;           /* official name of
net */
        char    FAR * FAR * n_aliases;  /* alias list */
        short   n_addrtype;             /* net address type
*/
        u_long  n_net;                  /* network # */
};

struct  servent {
        char    FAR * s_name;           /* official service
name */
        char    FAR * FAR * s_aliases;  /* alias list */
        short   s_port;                 /* port # */
        char    FAR * s_proto;          /* protocol to use
*/
};

struct  protoent {
        char    FAR * p_name;           /* official protocol
name */
        char    FAR * FAR * p_aliases;  /* alias list */
        short   p_proto;                /* protocol # */
};

/*
 * Constants and structures defined by the internet system,
 * Per RFC 790, September 1981, taken from the BSD file
netinet/in.h.
 */

/*
 * Protocols
 */
#define IPPROTO_IP              0               /* dummy for
IP */
#define IPPROTO_ICMP            1               /* control
message protocol */
#define IPPROTO_GGP             2               /* gateway^2
(deprecated) */
#define IPPROTO_TCP             6               /* tcp */
#define IPPROTO_PUP             12              /* pup */
#define IPPROTO_UDP             17              /* user
datagram protocol */
#define IPPROTO_IDP             22              /* xns idp
*/
#define IPPROTO_ND              77              /*
UNOFFICIAL net disk proto */

#define IPPROTO_RAW             255             /* raw IP
packet */
#define IPPROTO_MAX             256

/*
 * Port/socket numbers: network standard functions
 */
#define IPPORT_ECHO             7
#define IPPORT_DISCARD          9
#define IPPORT_SYSTAT           11
#define IPPORT_DAYTIME          13
#define IPPORT_NETSTAT          15
#define IPPORT_FTP              21
#define IPPORT_TELNET           23
#define IPPORT_SMTP             25
#define IPPORT_TIMESERVER       37
#define IPPORT_NAMESERVER       42
#define IPPORT_WHOIS            43
#define IPPORT_MTP              57

/*
 * Port/socket numbers: host specific functions
 */
#define IPPORT_TFTP             69
#define IPPORT_RJE              77
#define IPPORT_FINGER           79
#define IPPORT_TTYLINK          87
#define IPPORT_SUPDUP           95

/*
 * UNIX TCP sockets
 */
#define IPPORT_EXECSERVER       512
#define IPPORT_LOGINSERVER      513
#define IPPORT_CMDSERVER        514
#define IPPORT_EFSSERVER        520

/*
 * UNIX UDP sockets
 */
#define IPPORT_BIFFUDP          512
#define IPPORT_WHOSERVER        513
#define IPPORT_ROUTESERVER      520
                                        /* 520+1 also used
*/

/*
 * Ports < IPPORT_RESERVED are reserved for
 * privileged processes (e.g. root).
 */
#define IPPORT_RESERVED         1024

/*
 * Link numbers
 */
#define IMPLINK_IP              155
#define IMPLINK_LOWEXPER        156
#define IMPLINK_HIGHEXPER       158

/*
 * Internet address (old style... should be updated)
 */
struct in_addr {
        union {
                struct { u_char s_b1,s_b2,s_b3,s_b4; }
S_un_b;
                struct { u_short s_w1,s_w2; } S_un_w;
                u_long S_addr;
        } S_un;
#define s_addr  S_un.S_addr
                                /* can be used for most tcp
& ip code */
#define s_host  S_un.S_un_b.s_b2
                                /* host on imp */
#define s_net   S_un.S_un_b.s_b1
                                /* network */
#define s_imp   S_un.S_un_w.s_w2
                                /* imp */
#define s_impno S_un.S_un_b.s_b4
                                /* imp # */
#define s_lh    S_un.S_un_b.s_b3
                                /* logical host */
};

/*
 * Definitions of bits in internet address integers.
 * On subnets, the decomposition of addresses to host and
net parts
 * is done according to subnet mask, not the masks here.
 */
#define IN_CLASSA(i)            (((long)(i) & 0x80000000) ==
0)
#define IN_CLASSA_NET           0xff000000
#define IN_CLASSA_NSHIFT        24
#define IN_CLASSA_HOST          0x00ffffff
#define IN_CLASSA_MAX           128

#define IN_CLASSB(i)            (((long)(i) & 0xc0000000) ==
0x80000000)
#define IN_CLASSB_NET           0xffff0000
#define IN_CLASSB_NSHIFT        16
#define IN_CLASSB_HOST          0x0000ffff
#define IN_CLASSB_MAX           65536

#define IN_CLASSC(i)            (((long)(i) & 0xc0000000) ==
0xc0000000)
#define IN_CLASSC_NET           0xffffff00
#define IN_CLASSC_NSHIFT        8
#define IN_CLASSC_HOST          0x000000ff

#define INADDR_ANY              (u_long)0x00000000
#define INADDR_LOOPBACK         0x7f000001
#define INADDR_BROADCAST        (u_long)0xffffffff
#define INADDR_NONE             0xffffffff
/* Winsock extension */
#define ADDR_ANY                INADDR_ANY

/*
 * Socket address, internet style.
 */
struct sockaddr_in {
        short   sin_family;
        u_short sin_port;
        struct  in_addr sin_addr;
        char    sin_zero[8];
};

#define WSADESCRIPTION_LEN      256
#define WSASYS_STATUS_LEN       128

typedef struct WSAData {
        WORD                    wVersion;
        WORD                    wHighVersion;
        char
szDescription[WSADESCRIPTION_LEN+1];
        char
szSystemStatus[WSASYS_STATUS_LEN+1];
        unsigned short          iMaxSockets;
        unsigned short          iMaxUdpDg;
        char FAR *              lpVendorInfo;
} WSADATA;

typedef WSADATA FAR *LPWSADATA;


/*
 * Options for use with [gs]etsockopt at the IP level.
 */
#define IP_OPTIONS      1               /* set/get IP per-
packet options */

/*
 * Definitions related to sockets: types, address families,
options,
 * taken from the BSD file sys/socket.h.
 */

/*
 * This is used instead of -1, since the
 * SOCKET type is unsigned.
 */
#define INVALID_SOCKET  (SOCKET)(~0)
#define SOCKET_ERROR            (-1)

/*
 * Types
 */
#define SOCK_STREAM     1               /* stream socket */
#define SOCK_DGRAM      2               /* datagram socket
*/
#define SOCK_RAW        3               /* raw-protocol
interface */
#define SOCK_RDM        4               /* reliably-
delivered message */
#define SOCK_SEQPACKET  5               /* sequenced packet
stream */

/*
 * Types -- Winsock extensions for socket types with the
following convention
 *
SOCK[_REL|_UNREL][_ISOCH][_UNISEND|_UNIRECV][_STREAM|_DGRAM|
_DSTREAM]
 */
#define SOCK_REL_STREAM               SOCK_STREAM
#define SOCK_REL_DSTREAM              SOCK_SEQPACKET
#define SOCK_UNREL_DSTREAM            101
#define SOCK_REL_UNISEND_DSTREAM      102
#define SOCK_REL_UNIRECV_DSTREAM      103
#define SOCK_UNREL_UNISEND_DSTREAM    104
#define SOCK_UNREL_UNIRECV_DSTREAM    105
#define SOCK_REL_DGRAM                106
#define SOCK_UNREL_DGRAM              SOCK_DGRAM
#define SOCK_REL_ISOCH_DSTREAM        201
#define SOCK_UNREL_ISOCH_DSTREAM      202
#define SOCK_UNREL_ISOCH_STREAM       203

/*
 * Option flags per-socket.
 */
#define SO_DEBUG        0x0001          /* turn on debugging
info recording */
#define SO_ACCEPTCONN   0x0002          /* socket has had
listen() */
#define SO_REUSEADDR    0x0004          /* allow local
address reuse */
#define SO_KEEPALIVE    0x0008          /* keep connections
alive */
#define SO_DONTROUTE    0x0010          /* just use
interface addresses */
#define SO_BROADCAST    0x0020          /* permit sending of
broadcast msgs */
#define SO_USELOOPBACK  0x0040          /* bypass hardware
when possible */
#define SO_LINGER       0x0080          /* linger on close
if data present */
#define SO_OOBINLINE    0x0100          /* leave received
OOB data in line */

#define SO_DONTLINGER   (int)(~SO_LINGER)

/*
 * Additional options.
 */
#define SO_SNDBUF       0x1001          /* send buffer size
*/
#define SO_RCVBUF       0x1002          /* receive buffer
size */
#define SO_SNDLOWAT     0x1003          /* send low-water
mark */
#define SO_RCVLOWAT     0x1004          /* receive low-water
mark */
#define SO_SNDTIMEO     0x1005          /* send timeout */
#define SO_RCVTIMEO     0x1006          /* receive timeout
*/
#define SO_ERROR        0x1007          /* get error status
and clear */
#define SO_TYPE         0x1008          /* get socket type
*/

/*
 * Winsock extension -- options
 */
#define SO_FLOWSPEC       0x2001          /* flow spec for
sockets */
#define SO_GROUP_FLOWSPEC 0x2002          /* flow spec for
socket groups */
#define SO_GROUP_ID       0x2003          /* sharing the
same physical connection */
#define SO_GROUP_PRIORITY 0x2004          /* the relative
priority with a group */
#define SO_MAX_DG_SIZE    0x2005          /* maximum
datagram size */
#define PVD_CALL_ID       0x3001          /* an opaque
Winsock call ID */
#define PVD_CONFIG        0x3002          /* configuration
info for service provider */
#define TAPI_DEVICE_ID    0x3003          /* a TAPI line
device ID */

/*
 * TCP options.
 */
#define TCP_NODELAY     0x0001

/*
 * Address families.
 */
#define AF_UNSPEC       0               /* unspecified */
#define AF_UNIX         1               /* local to host
(pipes, portals) */
#define AF_INET         2               /* internetwork:
UDP, TCP, etc. */
#define AF_IMPLINK      3               /* arpanet imp
addresses */
#define AF_PUP          4               /* pup protocols:
e.g. BSP */
#define AF_CHAOS        5               /* mit CHAOS
protocols */
#define AF_NS           6               /* XEROX NS
protocols */
#define AF_ISO          7               /* ISO protocols */
#define AF_OSI          AF_ISO          /* OSI is ISO */
#define AF_ECMA         8               /* european computer
manufacturers */
#define AF_DATAKIT      9               /* datakit protocols
*/
#define AF_CCITT        10              /* CCITT protocols,
X.25 etc */
#define AF_SNA          11              /* IBM SNA */
#define AF_DECnet       12              /* DECnet */
#define AF_DLI          13              /* Direct data link
interface */
#define AF_LAT          14              /* LAT */
#define AF_HYLINK       15              /* NSC Hyperchannel
*/
#define AF_APPLETALK    16              /* AppleTalk */
#define AF_NETBIOS      17              /* NetBios-style
addresses */
/*
 * Address families -- Winsock extensions.
 */
#define AF_IPX          18              /* IPX/SPX addresses
*/
#define AF_POTS_IT      19              /* POTS addresses
for Intel Transport */
#define AF_ISDNQMUX_IT  20              /* ISDN addresses
for Intel Transport */
#define AF_INET_SPE     21              /* Internet (SPE
version) */
#define AF_IPX_SPE      22              /* IPX/SPX (SPE
version) */
#define AF_NETBIOS_SPE  23              /* NetBios (SPE
version) */

#define AF_MAX          24

/*
 * Structure used by kernel to store most
 * addresses.
 */
struct sockaddr {
        u_short sa_family;              /* address family */
        char    sa_data[14];            /* up to 14 bytes of
direct address */
};

/*
 * Structure used by kernel to pass protocol
 * information in raw sockets.
 */
struct sockproto {
        u_short sp_family;              /* address family */
        u_short sp_protocol;            /* protocol */
};

/*
 * Protocol families, same as address families for now.
 */
#define PF_UNSPEC       AF_UNSPEC
#define PF_UNIX         AF_UNIX
#define PF_INET         AF_INET
#define PF_IMPLINK      AF_IMPLINK
#define PF_PUP          AF_PUP
#define PF_CHAOS        AF_CHAOS
#define PF_NS           AF_NS
#define PF_ISO          AF_ISO
#define PF_OSI          AF_OSI
#define PF_ECMA         AF_ECMA
#define PF_DATAKIT      AF_DATAKIT
#define PF_CCITT        AF_CCITT
#define PF_SNA          AF_SNA
#define PF_DECnet       AF_DECnet
#define PF_DLI          AF_DLI
#define PF_LAT          AF_LAT
#define PF_HYLINK       AF_HYLINK
#define PF_APPLETALK    AF_APPLETALK
/*
 * Protocol families -- Winsock extension
 */
#define PF_IPX          AF_IPX
#define PF_POTS_IT      AF_POTS_IT
#define PF_ISDNQMUX_IT  AF_ISDNQMUX_IT
#define PF_INET_SPE     AF_INET_SPE
#define PF_IPX_SPE      AF_IPX_SPE
#define PF_NETBIOS_SPE  AF_NETBIOS_SPE

#define PF_MAX          AF_MAX

/*
 * Structure used for manipulating linger option.
 */
struct  linger {
        u_short l_onoff;                /* option on/off */
        u_short l_linger;               /* linger time */
};

/*
 * Level number for (get/set)sockopt() to apply to socket
itself.
 */
#define SOL_SOCKET      0xffff          /* options for
socket level */

/*
 * Winsock extension -- level number for
(get/set)socketopt() to apply to service provider
 *                  level.
 */
#define SOL_PROVIDER    IPPROTO_TCP     /* options for
service provider level */

/*
 * Maximum queue length specifiable by listen.
 */
#define SOMAXCONN       5

#define MSG_OOB         0x1             /* process out-of-
band data */
#define MSG_PEEK        0x2             /* peek at incoming
message */
#define MSG_DONTROUTE   0x4             /* send without
using routing tables */
#define MSG_INTERRUPT   0x8             /* interrupt-time
send or recv */

#define MSG_MAXIOVLEN   0x10

/*
 * Define constant based on rfc883, used by gethostbyxxxx()
calls.
 */
#define MAXGETHOSTSTRUCT        1024

/*
 * Winsock extension -- WSABUF and QOS struct
 */
typedef struct _WSABUF {
     int         len;     /* the length of the buffer */
     char FAR *  buf;     /* the pointer to the buffer */
} WSABUF, FAR * LPWSABUF;

typedef enum _GUARANTEE {
     GuaranteedService,
     BestEffortService
} GUARANTEE;

typedef struct _flowparams {
     int64          AverageBandwidth;   /* in bytes/sec */
     int64          PeakBandwidth;      /* in bytes/sec */
     int64          BurstLength;        /* in microseconds
*/
     int64          Latency;       /* in microseconds */
     int64          DelayVariation;     /* in microseconds
*/
     GUARANTEE LevelOfGuarantee;   /* guaranteed or best
effort */
     int32          CostOfCall          /* reserved for
future; must be zero */
     int32          ProviderId;         /* provider
identifier */
     int32          SizePSP;       /* length of provider
specific parameters */
     UCHAR          ProviderSpecificParams[1]; /* provider
specific parameters */
} FLOWPARAMS;

typedef struct _QOS {
     FLOWPARAMS     ForwardFP;          /* caller
(initiator) to callee */
     FLOWPARAMS     BackwardFP;         /* callee to caller
*/
} QOS, FAR * LPQOS;

/*
 * Winsock extension -- WSANETWORKEVENT
 */
typedef struct _WSANETWORKEVENT {
     BOOL Fired;
     int  ErrorCode;
} WSANETWORKEVENT, FAR * LPWSANETWORKEVENT;

/*
 * Winsock extension -- manifest constants for the return
value of the condition function
 */
#define CF_ACCEPT       0x0000
#define CF_REJECT       0x0001
#define CF_DEFER        0x0002

/*
 * Winsock extension -- manifest constants for shutdown()
 */
#define SD_RECEIVE      0x00
#define SD_SEND         0x01
#define SD_BOTH         0x02

/*
 * Winsock extension -- data type and manifest constants for
socket groups
 */
typedef unsigned int             GROUP;

#define SG_UNCONSTRAINED_GROUP   0x01
#define SG_CONSTRAINED_GROUP     0x02

/*
 * Define flags to be used with the WSPSelect() call.
 */
#define FD_READ         0x01L
#define FD_WRITE        0x02L
#define FD_OOB          0x04L
#define FD_ACCEPT       0x08L
#define FD_CONNECT      0x10L
#define FD_CLOSE        0x20L
/*
 * Winsock extension -- new flags for WSPSelect()
 */
#define FD_QOS          0x40L
#define FD_GROUP_QOS    0x80L

/*
 * All Winsock error constants are biased by WSABASEERR from
 * the "normal"
 */
#define WSABASEERR              10000
/*
 * Winsock definitions of regular Microsoft C error
constants
 */
#define WSAEINTR                (WSABASEERR+4)
#define WSAEBADF                (WSABASEERR+9)
#define WSAEACCES               (WSABASEERR+13)
#define WSAEFAULT               (WSABASEERR+14)
#define WSAEINVAL               (WSABASEERR+22)
#define WSAEMFILE               (WSABASEERR+24)

/*
 * Winsock definitions of regular Berkeley error constants
 */
#define WSAEWOULDBLOCK          (WSABASEERR+35)
#define WSAEINPROGRESS          (WSABASEERR+36)
#define WSAEALREADY             (WSABASEERR+37)
#define WSAENOTSOCK             (WSABASEERR+38)
#define WSAEDESTADDRREQ         (WSABASEERR+39)
#define WSAEMSGSIZE             (WSABASEERR+40)
#define WSAEPROTOTYPE           (WSABASEERR+41)
#define WSAENOPROTOOPT          (WSABASEERR+42)
#define WSAEPROTONOSUPPORT      (WSABASEERR+43)
#define WSAESOCKTNOSUPPORT      (WSABASEERR+44)
#define WSAEOPNOTSUPP           (WSABASEERR+45)
#define WSAEPFNOSUPPORT         (WSABASEERR+46)
#define WSAEAFNOSUPPORT         (WSABASEERR+47)
#define WSAEADDRINUSE           (WSABASEERR+48)
#define WSAEADDRNOTAVAIL        (WSABASEERR+49)
#define WSAENETDOWN             (WSABASEERR+50)
#define WSAENETUNREACH          (WSABASEERR+51)
#define WSAENETRESET            (WSABASEERR+52)
#define WSAECONNABORTED         (WSABASEERR+53)
#define WSAECONNRESET           (WSABASEERR+54)
#define WSAENOBUFS              (WSABASEERR+55)
#define WSAEISCONN              (WSABASEERR+56)
#define WSAENOTCONN             (WSABASEERR+57)
#define WSAESHUTDOWN            (WSABASEERR+58)
#define WSAETOOMANYREFS         (WSABASEERR+59)
#define WSAETIMEDOUT            (WSABASEERR+60)
#define WSAECONNREFUSED         (WSABASEERR+61)
#define WSAELOOP                (WSABASEERR+62)
#define WSAENAMETOOLONG         (WSABASEERR+63)
#define WSAEHOSTDOWN            (WSABASEERR+64)
#define WSAEHOSTUNREACH         (WSABASEERR+65)
#define WSAENOTEMPTY            (WSABASEERR+66)
#define WSAEPROCLIM             (WSABASEERR+67)
#define WSAEUSERS               (WSABASEERR+68)
#define WSAEDQUOT               (WSABASEERR+69)
#define WSAESTALE               (WSABASEERR+70)
#define WSAEREMOTE              (WSABASEERR+71)

/*
 * Extended Winsock error constant definitions
 */
#define WSASYSNOTREADY          (WSABASEERR+91)
#define WSAVERNOTSUPPORTED      (WSABASEERR+92)
#define WSANOTINITIALISED       (WSABASEERR+93)

/*
 * Error return codes from gethostbyname() and
gethostbyaddr()
 * (when using the resolver). Note that these errors are
 * retrieved via WSAGetLastError() and must therefore follow
 * the rules for avoiding clashes with error numbers from
 * specific implementations or language run-time systems.
 * For this reason the codes are based at WSABASEERR+1001.
 * Note also that [WSA]NO_ADDRESS is defined only for
 * compatibility purposes.
 */

#define h_errno         WSAGetLastError()

/* Authoritative Answer: Host not found */
#define WSAHOST_NOT_FOUND       (WSABASEERR+1001)
#define HOST_NOT_FOUND          WSAHOST_NOT_FOUND

/* Non-Authoritative: Host not found, or SERVERFAIL */
#define WSATRY_AGAIN            (WSABASEERR+1002)
#define TRY_AGAIN               WSATRY_AGAIN

/* Non recoverable errors, FORMERR, REFUSED, NOTIMP */
#define WSANO_RECOVERY          (WSABASEERR+1003)
#define NO_RECOVERY             WSANO_RECOVERY

/* Valid name, no data record of requested type */
#define WSANO_DATA              (WSABASEERR+1004)
#define NO_DATA                 WSANO_DATA

/* no address, look for MX record */
#define WSANO_ADDRESS           WSANO_DATA
#define NO_ADDRESS              WSANO_ADDRESS

/*
 * Winsock errors redefined as regular Berkeley error
constants
 */
#define EWOULDBLOCK             WSAEWOULDBLOCK
#define EINPROGRESS             WSAEINPROGRESS
#define EALREADY                WSAEALREADY
#define ENOTSOCK                WSAENOTSOCK
#define EDESTADDRREQ            WSAEDESTADDRREQ
#define EMSGSIZE                WSAEMSGSIZE
#define EPROTOTYPE              WSAEPROTOTYPE
#define ENOPROTOOPT             WSAENOPROTOOPT
#define EPROTONOSUPPORT         WSAEPROTONOSUPPORT
#define ESOCKTNOSUPPORT         WSAESOCKTNOSUPPORT
#define EOPNOTSUPP              WSAEOPNOTSUPP
#define EPFNOSUPPORT            WSAEPFNOSUPPORT
#define EAFNOSUPPORT            WSAEAFNOSUPPORT
#define EADDRINUSE              WSAEADDRINUSE
#define EADDRNOTAVAIL           WSAEADDRNOTAVAIL
#define ENETDOWN                WSAENETDOWN
#define ENETUNREACH             WSAENETUNREACH
#define ENETRESET               WSAENETRESET
#define ECONNABORTED            WSAECONNABORTED
#define ECONNRESET              WSAECONNRESET
#define ENOBUFS                 WSAENOBUFS
#define EISCONN                 WSAEISCONN
#define ENOTCONN                WSAENOTCONN
#define ESHUTDOWN               WSAESHUTDOWN
#define ETOOMANYREFS            WSAETOOMANYREFS
#define ETIMEDOUT               WSAETIMEDOUT
#define ECONNREFUSED            WSAECONNREFUSED
#define ELOOP                   WSAELOOP
#define ENAMETOOLONG            WSAENAMETOOLONG
#define EHOSTDOWN               WSAEHOSTDOWN
#define EHOSTUNREACH            WSAEHOSTUNREACH
#define ENOTEMPTY               WSAENOTEMPTY
#define EPROCLIM                WSAEPROCLIM
#define EUSERS                  WSAEUSERS
#define EDQUOT                  WSAEDQUOT
#define ESTALE                  WSAESTALE
#define EREMOTE                 WSAEREMOTE

#endif   /* _WS2API_ */

/*
 *  Winsock SPI socket function prototypes
 */

#ifdef __cplusplus
extern "C" {
#endif

typedef BOOL ( WSACALLBACK * LPBLOCKINGPROC )( VOID );

typedef VOID ( WSACALLBACK * LPCLEANUPPROC )( int ErrorCode,
                                              DWORD
dwCallbackData );

typedef int ( WSACALLBACK * LPCONDITIONPROC )( LPWSABUF
lpCallerId,
                                               LPWSABUF
lpCallerData,
                                               LPWSABUF
lpCalleeId,
                                               LPWSABUF
lpCalleeData,
                                               GROUP FAR *
g,
                                               DWORD
dwCallbackData );

typedef VOID ( WSACALLBACK LPSELECTPROC )( SOCKET s,
                                           long lEvent,
                                           int ErrorCode,
                                           DWORD
dwCallbackData );

typedef VOID ( FAR * LPWSAUSERAPC )( DWORD dwContext );

SOCKET PASCAL FAR PSaccept (SOCKET s,
                            struct sockaddr FAR *addr,
                            int FAR *addrlen,
                            int FAR * lpErrno);

int WSPAPI WSPBindWSPbind( SOCKET s,
                    const struct sockaddr FAR *name,
                    int namelen,
                    int FAR * lpErrno );

int WSPAPI WSPCloseSocketWSPclosesocket( SOCKET s,
                           int FAR * lpErrno );

int PASCAL FAR PSconnect (SOCKET s,
                          const struct sockaddr FAR *name,
                          int namelen,
                          int FAR * lpErrno);

int WSPAPI WSPGetPeerNameWSPgetpeername( SOCKET s,
                           struct sockaddr FAR *name,
                           int FAR * namelen,
                           int FAR * lpErrno );

int WSPAPI WSPGetSockNameWSPgetsockname( SOCKET s,
                           struct sockaddr FAR *name,
                           int FAR * namelen,
                           int FAR * lpErrno );

int WSPAPI WSPGetSockOptWSPgetsockopt( SOCKET s,
                          int level,
                          int optname,
                          char FAR * optval,
                          int FAR *optlen,
                          int FAR * lpErrno );

int WSPAPI WSPIoctlSocketWSPioctlsocket( SOCKET s,
                           long cmd,
                           u_long FAR *argp,
                           int FAR * lpErrno );

int WSPAPI WSPListenWSPlisten( SOCKET s,
                      int backlog,
                      int FAR * lpErrno );

int WSPAPI WSPSelectWSPselect( int nfds,
                      fd_set FAR *readfds,
                      fd_set FAR *writefds,
                      fd_set FAR *exceptfds,
                      const struct timeval FAR *timeout,
                      int FAR * lpErrno );

int WSPAPI WSPSetSockOptWSPsetsockopt( SOCKET s,
                          int level,
                          int optname,
                          const char FAR * optval,
                          int optlen,
                          int FAR * lpErrno );

int WSPAPI WSPShutdownWSPshutdown( SOCKET s,
                        int how,
                        int FAR * lpErrno );

/* Microsoft Windows Extension function prototypes */

SOCKET WSPAPI WSPAccept( SOCKET s,
                         struct sockaddr FAR *addr,
                         int FAR *addrlen,
                         LPCONDITIONPROC lpfnCondition,
                         DWORD dwCallbackData,
                         int FAR * lpErrno );

int WSPAPI WSPAsyncSelect32( SOCKET s,
                             HWND hWnd,
                             unsigned int wMsg,
                             long lEvnet,
                             int FAR * lpErrno );

int WSPAPI WSPCallbackSelect16( SOCKET s,
                                LPSELECTPROC lpfnCallback,
                                DWORD dwCallbackData,
                                long lEvent,
                                int FAR * lpErrno );

int WSPAPI WSPCancelBlockingCall32( int FAR * lpErrno );

int WSPAPI WSPCleanup( LPCLEANUPPROC lpfnCallback,
                       DWORD dwCallbackData,
                       int FAR * lpErrno );

int WSPAPI WSPConnect( SOCKET s,
                       const struct sockaddr FAR *name,
                       int namelen,
                       LPWSABUF lpCallerData,
                       LPWSABUF lpCalleeData,
                       GROUP g,
                       LPQOS lpSFlowspec,
                       LPQOS lpGFlowspec,
                       int FAR * lpErrno );

int WSPAPI WSPEnumNetworkEvents( SOCKET s,
                                 WSAEVNET hEventObject,
                                 LPWSANETWORKEVENT
lpNetworkEvents,
                                 LPINT lpiCount,
                                 int FAR * lpErrno  );

int WSPAPI WSPEventSelect( SOCKET s,
                           WSAEVENT hEventObject,
                           long lNetworkEvents,
                           int FAR * lpErrno  );

BOOL WSPAPI WSPIsBlocking32( VOID );

int WSPAPI WSPRecvWSPrecv( SOCKET s,
                    LPVOID lpBuffer,
                    DWORD nNumberOfBytesToRecv,
                    LPDWORD lpNumberOfBytesRecvd,
                    LPINT lpFlags,
                    LPWSAOVERLAPPED lpOverlapped,
                    LPWSAOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine,
                    int FAR * lpErrno );

int WSPAPI WSPRecvFromWSPrecvfrom( SOCKET s,
                        LPVOID lpBuffer,
                        DWORD nNumberOfBytesToRecv,
                        LPDWORD lpNumberOfBytesRecvd,
                        LPINT lpFlags,
                        LPVOID lpFrom,
                        LPINT lpFromlen,
                        LPWSAOVERLAPPED lpOverlapped,
                        LPWSAOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine,
                        int FAR * lpErrno );

int WSPAPI WSPSendWSPsend( SOCKET s,
                    LPVOID lpBuffer,
                    DWORD nNumberOfBytesToSend,
                    LPDWORD lpNumberOfBytesSent,
                    int nFlags,
                    LPWSAOVERLAPPED lpOverlapped,
                    LPWSAOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine,
                    int FAR * lpErrno );

int WSPAPI WSPSendToWSPsendto( SOCKET s,
                      LPVOID lpBuffer,
                      DWORD nNumberOfBytesToSend,
                      LPDWORD lpNumberOfBytesSent,
                      int nFlags,
                      LPVOID lpTo,
                      int nTolen,
                      LPWSAOVERLAPPED lpOverlapped,
                      LPWSAOVERLAPPED_COMPLETION_ROUTINE
lpCompletionRoutine,
                      int FAR * lpErrno );

LPBLOCKINGPROC WSPAPI WSPSetBlockingHook32( LPBLOCKINGPROC
lpBlockFunc,
                                            int FAR *
lpErrno );

SOCKET WSPAPI WSPSocket( int af,
                         int type,
                         int protocol,
                         DWORD dwProviderId,
                         int nFlags,
                         int FAR * lpErrno );

int WSPAPI WSPStartup( WORD wVersionRequired,
                       LPWSADATA lpWSAData );

int WSPAPI WSPUnhookBlockingHook32( int FAR * lpErrno );

/* Upcalls from service providers to the Winsock DLL */

SOCKETWSPAPI WPUXxxCreateSocketHandle( DWORD dwProviderId,
                                    LPVOID lpContext,
                                    int FAR * lpErrno );

int WSPAPI WPUXxxCloseSocketHandle( SOCKET s,
                                 int FAR * lpErrno );

int WSPAPI WPUXxxQuerySocketHandleContext( SOCKET s,
                                        LPVOID FAR *
lpContext,
                                        int FAR * lpErrno );

int WSPAPI WPUXxxSetSocketHandleContext( SOCKET s,
                                      LPVOID lpContext,
                                      int FAR * lpErrno );

int WSPAPI WPUXxxQueueUserAPC32UserAPC( DWORD dwThreadId,
                              LPWSAUSERAPC lpfnUserApc,
                              DWORD dwContext,
                              int FAR * lpErrno );

DWORD WSPAPI WPUXxxGetCurrentThreadId32( VOID );

#ifdef __cplusplus
}
#endif

#ifndef _WS2API_

/* Microsoft Windows Extended data types */
typedef struct sockaddr SOCKADDR;
typedef struct sockaddr *PSOCKADDR;
typedef struct sockaddr FAR *LPSOCKADDR;

typedef struct sockaddr_in SOCKADDR_IN;
typedef struct sockaddr_in *PSOCKADDR_IN;
typedef struct sockaddr_in FAR *LPSOCKADDR_IN;

typedef struct linger LINGER;
typedef struct linger *PLINGER;
typedef struct linger FAR *LPLINGER;

typedef struct in_addr IN_ADDR;
typedef struct in_addr *PIN_ADDR;
typedef struct in_addr FAR *LPIN_ADDR;

typedef struct fd_set FD_SET;
typedef struct fd_set *PFD_SET;
typedef struct fd_set FAR *LPFD_SET;

typedef struct hostent HOSTENT;
typedef struct hostent *PHOSTENT;
typedef struct hostent FAR *LPHOSTENT;

typedef struct servent SERVENT;
typedef struct servent *PSERVENT;
typedef struct servent FAR *LPSERVENT;

typedef struct protoent PROTOENT;
typedef struct protoent *PPROTOENT;
typedef struct protoent FAR *LPPROTOENT;

typedef struct timeval TIMEVAL;
typedef struct timeval *PTIMEVAL;
typedef struct timeval FAR *LPTIMEVAL;

/*
 * Windows message parameter composition and decomposition
 * macros.
 *
 * WSAMAKEASYNCREPLY is intended for use by Winsock
 * when constructing the response to a WSAAsyncGetXByY()
routine.
 */
#define WSAMAKEASYNCREPLY(buflen,error)
MAKELONG(buflen,error)
/*
 * WSAMAKESELECTREPLY is intended for use by Winsock
 * when constructing the response to WSAAsyncSelect().
 */
#define WSAMAKESELECTREPLY(event,error)
MAKELONG(event,error)
/*
 * WSAGETASYNCBUFLEN is intended for use by the Winsock
application
 * to extract the buffer length from the lParam in the
response
 * to a WSAGetXByY().
 */
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
/*
 * WSAGETASYNCERROR is intended for use by the Winsock
application
 * to extract the error code from the lParam in the response
 * to a WSAGetXByY().
 */
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
/*
 * WSAGETSELECTEVENT is intended for use by the Winsock
application
 * to extract the event code from the lParam in the response
 * to a WSAAsyncSelect().
 */
#define WSAGETSELECTEVENT(lParam)           LOWORD(lParam)
/*
 * WSAGETSELECTERROR is intended for use by the Winsock
application
 * to extract the error code from the lParam in the response
 * to a WSAAsyncSelect().
 */
#define WSAGETSELECTERROR(lParam)           HIWORD(lParam)

#endif  /* _WS2API_ */

#endif  /* _WS2SPI_ */


Appendix B. Notes for Winsock Service Providers
B.1 Introduction

A Winsock service provider must implement ALL of the
applicable functionality described in the Winsock SPI
documentation. Validation of compliance is discussed in
section Error! Reference source not found.Error! Reference
source not found.Error! Reference source not found..

PII Version 1.1 implementations must support both TCP and
UDP type sockets.  An implementation may support raw sockets
(of type SOCK_RAW), but their use is deprecated.

Certain Winsock SPIs documented above have special notes for
Winsock service provider implementors. A Winsock service
provider should pay special attention to conforming to the
Winsock SPI as documented. The Special Notes are provided
for assistance and clarification.

B.2 Winsock SPI Run Time Components

The run time component provided by each Winsock supplier is:

Component           Description
Installation Program     The Winsock service provider
                    installation program
Service Provider DLL     The Winsock service provider
                    implementation DLL

B.3 Error Codes

In order to avoid conflict between various compiler
environments Winsock service providers MUST return the error
codes listed in the SPI 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 ported from other
platforms.
Appendix C. Outstanding Issues

  1.   Does the 32-bit Windows Sockets 2 implementation live
     in WSOCK32.DLL or WSOCK232.DLL?
  
  What is the exact mechanism used for routing socket
     handle-based requests to the proper provider? This
     mechanism needs to be cognizant of TDI providers that
     use "real" file system handles. {Is this an
     architectural issue or an implementation issue. I would
     suggest we avoid raising implimentation issues in our
     public forum at this point in time.}
  Does Windows 95 support 16- and 32-bit providers? If so,
     the registry layout may need to be changed slighly to
     specify both 16- and 32-bit provider DLLs. The registry
     could be split into 16- and 32-bit subtrees, or
     separate registry values could be used for the 16- and
     32-bit DLLs. {I thought we had decided that there would
     only be 32 bit providers in Windows 95}
  The (16- and 32-bit) Windows Sockets DLLs could provide
     "up call" entrypoints for use by the provider DLLs to
     simplify configuration management. The Windows Sockets
     DLLs could also provide entrypoints to simplify
     provider installation. {Are these different upcalls
     than are already included in this document? If so, I'm
     not sure what you mean by "simplify configuration
     mgmt". I believe we made a decision that the Winsock
     DLLs would in fact provide entry points to simplify
     installation. Even if we don't have these ready at this
     time, we should put a place holder for them in the main
     body of the document and not show them as an open
     issue. }
  2.   Do the 16- and 32-bit providers use the same header
     file (ws2spi.h)?
  
  Need proper prefix for upcalls ("Xxx" is obviously just a
     place-holder). {How about WSU for Winsock upcall ? It
     would be nice not to have a relatively minor point like
     this left in the Opens section.}
  3.   Should SPI functions that take socket descriptors also
     take a context value? For providers that use "real" system
     handles, this could always be NULL.
  Should we support the SPI version as a separate concept
     from the API version? {I think we are already set up to
     be able to do this since we have separate version
     negotiations between App and DLL and between DLL and
     SP.}
  Does the 32-bit WSPCleanup() really use the callback
     function? {Again, is this architecture or
     implementation? If implementation, lets move this to a
     private list of implementation issues.}
  4.   How does a DLL-based protocol support graceful socket
     close if an app immediately exits after calling
     closesocket()? The provider & protocol DLLs will be detached
     from the process (whose address space will go away
     entirely), yet socket state needs to "linger" for the
     graceful close.
  5.   Does the Winsock DLL close all sockets before calling
     WSPCleanup(), or is WSPCleanup() responsible for closing all
     open sockets?
_______________________________
1Note that there is a timing window between the accept()
call and the call to WSAAsyncSelect() to change the events
or wMsg.  An application which desires a different wMsg for
the listening and accept()'ed sockets should ask for only
FD_ACCEPT events on the listening socket, then set
appropriate events after the accept().  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.
2 Because the callback is accessed at interrupt time, it
must reside in a DLL, and its code segment must be specified
as FIXED in the module-definition file for the DLL. Any data
that the callback accesses must be in a FIXED data segment
as well. The callback may not make any system calls except
for PostMessage, timeGetSystemTime, timeGetTime,
timeSetEvent, timeKillEvent, midiOutShortMsg,
midiOutLongMsg, and OutputDebugStr.
3 Note that there is a potential race condition here:
WINSOCK 2..DLL may get FD_READ,  FD_WRITE or FD_ACCEPT
callback in interrupt time before it returns from
WSPAcceptEx().  Similar situations may happen to
PSConnectEx(), andany of the reenabling functions if they
are not invoked from within callback context.
4 However, due to the independence feature of sockets,
WINSOCK2.DLL may get a callback for one socket before the
callback for another socket has returned.  WINSOCK2.DLL may
need to coordinate access to any common memory area shared
amongst these callback driven sockets.
5 Note that there is a potential race condition here:
WINSOCK2.DLL may get a callback in interrupt time even
before returning from WSPCallbackSelect(), in which case
WINSOCK2.DLL should proceed with the callback and assume
that WSPCallbackSelect() will return 0.
6Note that there is a timing window between the accept()
call and the call to WSAEventSelect() to change the network
events or hEventObject.  An application which desires a
different hEventObject for the listening and accept()'ed
sockets should ask for only FD_ACCEPT network event on the
listening socket, then set appropriate network events after
the accept().  Since FD_ACCEPT never happens to a connected
socket and FD_READ, FD_WRITE, FD_OOB, and FD_CLOSE never
happen to listening sockets, this will not impose
difficulties.