Windows Sockets

An Open Interface for Network Programming under Microsoft Windows

Version 1.1

20 January 1993

Table of Contents


Appendix B. Notes for Windows Sockets Suppliers

B.1 Introduction

A Windows Sockets implementation must implement ALL the functionality described in the Windows Sockets documentation. Validation of compliance is discussed in section B.8.

Windows Sockets 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 APIs documented above have special notes for Windows Sockets implementors. A Windows Sockets implementation should pay special attention to conforming to the API as documented. The Special Notes are provided for assistance and clarification.

B.2 Windows Sockets Components

B.2.1 Development Components

The Windows Sockets development components for use by Windows Sockets application developers will be provided by each Windows Sockets supplier. These Windows Sockets development components are:
Component                       Description
Windows Sockets Documentation   This document
WINSOCK.LIB file                Windows Sockets API Import Library
WINSOCK.H file                  Windows Sockets Header File
NETDB.H file                    Berkeley Compatible Header File
ARPA/INET.H file                Berkeley Compatible Header File
SYS/TIME.H file                 Berkeley Compatible Header File
SYS/SOCKET.H file               Berkeley Compatible Header File
NETINET/IN.H file               Berkeley Compatible Header File

B.2.2 Run Time Components

The run time component provided by each Windows Sockets supplier is:
Component                       Description
WINSOCK.DLL                     The Windows Sockets API implementation DLL

B.3 Multithreadedness and blocking routines.

Data areas returned by, for example, the getXbyY() routines MUST be on a per thread basis.

Note that an application MUST be prevented from making multiple nested Windows Sockets function calls. Only one outstanding function call will be allowed for a particular task. Any Windows Sockets call performed when an existing blocking call is already outstanding will fail with an error code of WSAEINPROGRESS. There are two exceptions to this restriction: WSACancelBlockingCall() and WSAIsBlocking() may be called at any time. Windows Sockets suppliers should note that although preliminary drafts of this specification indicated that the restriction only applied to blocking function calls, and that it would be permissible to make non-blocking calls while a blocking call was in progress, this is no longer true.

Regarding the implementation of blocking routines, the solution in Windows Sockets is to simulate the blocking mechanism by having each routine call PeekMessage() as it waits for the completion of its operation. In anticipation of this, the function WSASetBlockingHook() is provided to allow the programmer to define a special routine to be called instead of the default PeekMessage() loop. The blocking hook functions are discussed in more detail in 4.3.13, WSASetBlockingHook().

B.4 Database Files

The database routines in the getXbyY() family (gethostbyaddr(), etc.) were originally designed (in the first Berkeley UNIX releases) as mechanisms for looking up information in text databases. A Windows Sockets supplier may choose to employ local files OR a name service to provide some or all of this information. If local files exist, the format of the files must be identical to that used in BSD UNIX, allowing for the differences in text file formats.

B.5 FD_ISSET

It is necessary to implement the FD_ISSET Berkeley macro using a supporting function: __WSAFDIsSet(). It is the responsibility of a Windows Sockets implementation to make this available as part of the Windows Sockets API. Unlike the other functions exported by a Windows Sockets DLL, however, this function is not intended to be invoked directly by Windows Sockets applications: it should be used only to support the FD_ISSET macro. The source code for this function is listed below:
int FAR
__WSAFDIsSet(SOCKET fd, fd_set FAR *set)
{
    int i = set->fd_count;

    while (i--)
        if (set->fd_array[i] == fd)
            return 1;

    return 0;
}

B.6 Error Codes

In order to avoid conflict between various compiler environments Windows Sockets implementations MUST return the error codes listed in the API specification, using the manifest constants beginning with "WSA". The Berkeley-compatible error code definitions are provided solely for compatibility purposes for applications which are being ported from other platforms.

B.7 DLL Ordinal Numbers

The winsock.def file for use by every Windows Sockets implementation is as follows. Ordinal values starting at 1000 are reserved for Windows Sockets implementors to use for exporting private interfaces to their DLLs. A Windows Sockets implementation must not use any ordinals 999 and below except for those APIs listed below. An application which wishes to work with any Windows Sockets DLL must use only those routines listed below; using a private export makes an application dependent on a particular Windows Sockets implementation.
;
;         File: winsock.def
;       System: MS-Windows 3.x
;      Summary: Module definition file for Windows Sockets DLL.
;

LIBRARY         WINSOCK         ; Application's module name

DESCRIPTION     'BSD Socket API for Windows'

EXETYPE         WINDOWS         ; required for all windows applications

STUB            'WINSTUB.EXE'   ; generates error message if application
                                ; is run without Windows

;CODE can be FIXED in memory because of potential upcalls
CODE            PRELOAD         FIXED

;DATA must be SINGLE and at a FIXED location since this is a DLL
DATA            PRELOAD         FIXED           SINGLE

HEAPSIZE        1024
STACKSIZE       16384

; All functions that will be called by any Windows routine
; must be exported.  Any additional exports beyond those defined
; here must have ordinal numbers 1000 or above.

EXPORTS
        accept                         @1
        bind                           @2
        closesocket                    @3
        connect                        @4
        getpeername                    @5
        getsockname                    @6
        getsockopt                     @7
        htonl                          @8
        htons                          @9
        inet_addr                      @10
        inet_ntoa                      @11
        ioctlsocket                    @12
        listen                         @13
        ntohl                          @14
        ntohs                          @15
        recv                           @16
        recvfrom                       @17
        select                         @18
        send                           @19
        sendto                         @20
        setsockopt                     @21
        shutdown                       @22
        socket                         @23

        gethostbyaddr                  @51
        gethostbyname                  @52
        getprotobyname                 @53
        getprotobynumber               @54
        getservbyname                  @55
        getservbyport                  @56
        gethostname                    @57

        WSAAsyncSelect                 @101
        WSAAsyncGetHostByAddr          @102
        WSAAsyncGetHostByName          @103
        WSAAsyncGetProtoByNumber       @104
        WSAAsyncGetProtoByName         @105
        WSAAsyncGetServByPort          @106
        WSAAsyncGetServByName          @107
        WSACancelAsyncRequest          @108
        WSASetBlockingHook             @109
        WSAUnhookBlockingHook          @110
        WSAGetLastError                @111
        WSASetLastError                @112
        WSACancelBlockingCall          @113
        WSAIsBlocking                  @114
        WSAStartup                     @115
        WSACleanup                     @116

        __WSAFDIsSet                   @151

        WEP                            @500    RESIDENTNAME

;eof

B.8 Validation Suite

The Windows Sockets API Tester (WSAT) to ensure Windows Sockets compatibility between Windows Sockets DLL implementations is currently in beta test. This beta version includes functionality testing of the Windows Sockets interface and is supported by a comprehensive scripting language. The final version of WSAT will be available in Spring 1993. If you wish to receive the tester or more information on the beta, send email to wsat@microsoft.com.


NEXT PREVIOUS CONTENTS