Iczelion's Guide to Winsock Programming

Types of Socket
There are two types of socket: stream socket and datagram socket. A stream socket makes use of TCP so its transmission requires connection and is reliable. You use a stream socket when you want to send large files over the net or you want sequenced data packets (that is, the order of data packets is important). A datagram socket provides simple transfer of data. It's not guaranteed to be reliable (the data may not reach its destination), sequenced (the data packets may arrive in different order than intended), or unduplicated (the destination socket may receive two or more identical copies of the same data packets). HTTP and FTP and some other protocols use stream sockets while some broadcast protocols use datagram sockets.
You can think of stream socket connection as a telephone chat. You first have to make a call and if the call is successful, a connection is established. Then you can exchange information with the other end in a reliable way. If some communication problem occurs you know of it immediately and can take measures to rectify it. Datagram socket connection is like sending several mails to someone. You cannot know beforehand that they will reach the intended person. Even if he received them, there's no guarantee that the mails will reach him in the order you sent. And the mails may not reach the target at all.
The socket model sometimes uses client-server concept that is, one socket is thought of as server since it has services that it can render for other sockets, the opposite end is the client which asks the server for some services. HTTP and FTP make uses of this client-server concept.

Byte Ordering
Since we must deal with IP addresses in winsock programming, we should know of different byte ordering first. There are two types of byte ordering: big Endian and little Endian. In big Endian scheme, the leftmost byte are stored in the most significant byte. Little Endian scheme is the reverse of big Endian. For example, if the IP address is 205.34.67.24, in big Endian scheme it will be 205 34 67 24. But in little Endian, it will be 24 67 34 205.
Intel CPU uses little endian while some other CPUs such as Motorola uses big endian. The final word is: the internet uses big endian scheme so if you use a CPU with little endian byte ordering, you must convert the IP addresses before using them with the net.

Blocking and non-blocking modes
Socket functions can operate in two modes: blocking and non-blocking. Originally, in Berkeley Unix implementation, the sockets operate in blocking mode, that is, a socket function will not return until the operation is completed. We can call "blocking mode" synchronous operation and "non-blocking mode" asynchronous operation. Blocking operation may take an arbitrarily long time to complete such as waiting for the data to arrive from the remote socket. During that time, the program will seem frozen. This is usually unacceptable in Windows environment. So Windows implementation of socket API includes asynchronous (non-blocking) versions of the original blocking functions. You should use non-blocking versions whenever possible since it conforms to Windows paradigm and provides better results than the blocking ones.

Ports
When you create a socket and connect it to the remote socket, you must specify the port that the sockets will communicate with each other. Ports in this case is not hardware ports like COM1 or COM2. Ports in winsock programming are virtual ones for communication purpose only. Maybe an example will make this clear. Say, the server creates a socket and instructs it to listen for incoming connection on port 21, although there may be many network packets coming into the server, those packets that are destined for port number 21 will be routed to that socket. Several Internet protocols has their own default ports. HTTP uses port 80 (decimal) and FTP uses port 21 (decimal). These are default ports only. It means if both client and server agree to communicate via different ports, they can do so without any repercussion.

Winsock Programming Overview
Programming winsock normally includes these steps:

1. Initialize winsock dll
2. Create socket
3. Specify the operation mode: blocking or non-blocking
4. Connect the socket
5. Perform some tasks with the socket such as sending or receiving data
6. Close the socket
7. Release winsock dll

WSAStartup PROTO wVersionRequired:DWORD, LPWSADATA:DWORD

Return Value
WSAStartup returns NULL if the call is successful. Otherwise it returns error code. You can look up the error codes in winsock.hlp. This is the only winsock function that returns the actual error code because you cannot call WSAGetLastError if the socket dll is not initialized first.

Comment
If this function is not successful, you cannot use any winsock function. In fact, this function also serves as a negotiation routine for the best version of winsock api service for the application. After the call is successful, WSADATA structure will be filled with the capabilities of the current winsock implementation. One of the members is the highest version of winsock that the library supports. Say, if the application requests for at least winsock version 1.1 support and the current winsock library can support version 2, WSAStartup call will be successful and the winsock library returns 200h in a member of WSADATA. If the application can make use of winsock 2 support, it may call WSACleanup to close the previous initialization and call WSAStartup again, this time with 200h in its wVersionRequired parameter. If your application supports only winsock 1.1, you don't have to examine the WSADATA structure.

Code Snippet:

.data
wsadata WSADATA <>
.....
.code
.......
invoke WSAStartup, 101h,addr wsadata
.if eax!=NULL
    <An error occured>
.else
    <The initialization is successful. You may proceed with other winsock calls>
.endif

socket PROTO af:DWORD, type:DWORD, protocol:DWORD

Return Value
If the call is unsuccessful, the return value is INVALID_SOCKET and you can call WSAGetLastError to retrieve the actual error code. If the call is successful, it returns the socket descriptor which you must use in subsequent winsock calls.

Comment:
You must create at least one socket to be used as the communication device from your end. After successful call, you must save the returned socket descriptor for use with subsequent winsock function calls.

Code Snippet:

.data?
sock dd ?
....
.code
....
invoke socket,AF_INET,SOCK_STREAM,0     ; Create a stream socket for internet use
.if eax!=INVALID_SOCKET
    mov sock,eax
.else
    invoke WSAGetLastError
    ...
.endif

WSAAsyncSelect PROTO socket:DWORD, hwnd:DWORD, msg:DWORD, Event:DWORD

• 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
Out-of-band data deserves some explanation here. Out-of-band data is the data that are sent without regard to the normal order of the general data. You can think of out-of-band data as an emergency notification as such it must be distinguished from the normal data. There are two ways to receive out-of-band data: in-line and separate channel. Normally, winsock library will put out-of-band data in a separate channel by default and will notify the application when out-of-band data arrive. However, some application may want to receive out-of-band data in the same channel as the normal data. In this case, that application must call setsockopt to modify SO_OOBINLINE option and call ioctlsocket to check if there are some out-of-band data in the socket.

Comment
This function is the instrument of non-blocking paradigm. It lets an application specify which winsock events it's interested in and when the registered winsock events occur, the winsock library will send the specified message to the window. Contrast this to the blocking scenario in which you must poll for the winsock events. This function also changes the socket to non-blocking mode. I recommend that you use WSAAsyncSelect whenever applicable since it conforms to Windows paradigm.
If you don't want the winsock library to send notifications to your window anymore, you must call WSAAsyncSelect with value 0 in lEvent parameter. However, beware that there may be winsock messages in the queue before you cancel winsock notification. You must be prepared to handle them. Normally you should extract them from the message queue by PeekMessage call with PM_REMOVE flag.
When a winsock event that the application is interested occurs, the message specified by msg parameter will be sent to the window procedure of the window specified by hwnd parameter. With the message, wParam contains the socket descriptor, high word of lParam contains error code (if any) and the low word of lParam contains the event.

Code Snippet

.data?
hwnd dd ?            ; handle of the window to receive the winsock message.
socket dd ?           ; socket descriptor
....
.const
WM_SOCKET equ WM_USER+100    ; create a custom window message. You can use any name not
                                                                     ; limited to WM_SOCKET and you can use any number not
                                                                     ; limited to 100.
......
.code
...........
invoke WSAAsyncSelect, socket, hwnd,WM_SOCKET, FD_CONNECT+FD_READ+FD_CLOSE
            ; Register interest in connect, read and close events.
.if eax==SOCKET_ERROR
    <put your error handling routine here>
.else
    ........
.endif

WndProc PROC hWnd:DWORD, uMsg:DWORD, wParam:DWORD, lParam:DWORD
    .......
    .if uMsg==WM_SOCKET            ; the message we specified in WSAAsyncSelect
        mov eax,lParam
        .if ax==FD_CONNECT            ; the low word of lParam contains the event code.
            shr eax,16                              ; the error code (if any) is in the high word of lParam
            .if ax==NULL
                <no error occurs so proceed>
            .else
                <an error occurs. Put your error handling routine here>
            .endif
        .elseif    ax==FD_READ
            shr eax,16
            .if ax==NULL
                <no error occurs so proceed>
            .else
                <an error occurs. Put your error handling routine here>
            .endif
        .elseif    ax==FD_CLOSE
            shr eax,16
            .if ax==NULL
                <no error occurs so proceed>
            .else
                <an error occurs. Put your error handling routine here>
            .endif
        .endif
    .else
        ..........
    .endif
WndProc ENDP

connect PROTO socket:DWORD, lpSockAddr_in:DWORD, namelen:DWORD

sockaddr_in STRUCT
  sin_family  WORD      ?
  sin_port  WORD      ?
  sin_addr  DWORD      ?
  sin_zero  BYTE 8 dup (?)
sockaddr_in ENDS

You must fill in this structure and pass its address to connect.
 

• sin_family is the same as af parameter in socket call. You must use AF_INET here.
• sin_port is the port that the socket will use to communicate with the remote socket. This value depends on the higher level protocol that you want to use. If you want to connect to the remote socket for HTTP, use port 80 (decimal). However, note that the port value MUST be in network byte order that is big Endian. So you cannot use the port value per se but you must call htons to convert the value to network byte order first. This is one of the most common error the newcomers to winsock programming encounter.
• sin_addr is the IP address of the remote host. Again, you must convert the IP address to network byte order before using it.
• sin_zero is reserved. Don't mess with it.

Return Value
Depend on the mode of the socket.

• non-blocking mode: it returns SOCKET_ERROR and you must call WSAGetLastError to retrieve the error code. If the error code is WSAEWOULDBLOCK ,it means that the operation is in progress and cannot return immediately. The application will be informed of the result later by custom window message specified in WSAAsyncSelect call. In a nutshell, WSAEWOULDBLOCK is not an error.
• blocking mode: The return value indicates the success or failure of the call.

 .data
sin SOCKADDR_IN <>
IPAddress db "206.34.234.23",0
Port dd 80                    ; We use port 80, HTTP port for demonstration purpose

.data?
socket dd ?

.code
........
mov sin.sin_family, AF_INET
invoke htons, Port                    ; convert port number into network byte order first
mov sin.sin_port,ax                  ; note that this member is a word-size param.
invoke inet_addr, addr IPAddress    ; convert the IP address into network byte order
mov sin_addr,eax
invoke connect,socket,addr sin,sizeof sin
.if eax==SOCKET_ERROR            ; assuming we use non-blocking mode, connect
                                                            ; will always return SOCKET_ERROR
    invoke WSAGetLastError            ; retrieve the actual error code
    .if eax!=WSAEWOULDBLOCK        ; if it's not WSAEWOULDBLOCK
        <put your error handling code here>        ; it means a true error occurred
    .endif
.endif

gethostbyname PROTO lphostname:DWORD

Return Value
If successful, it returns a pointer to hostent structure which is allocated by Windows sockets implementation. If the call fails, it returns NULL and you may call WSAGetLastError to retrieve the error code.

hostentStru STRUCT
  h_name      DWORD      ?
  h_alias     DWORD      ?
  h_addr      WORD      ?
  h_len       WORD      ?
  h_list      DWORD    ?
hostentStru ENDS

h_name Official name of the host (PC).
h_alias A NULL-terminated array of alternate names.
h_addr  The type of address being returned; for Windows Sockets this is always PF_INET.
h_len  The length, in bytes, of each address; for PF_INET, this is always 4.
h_list  Pointer to a pointer that points to the list of ip addresses. In summary, h_list is a double pointer indirection. Addresses are returned in network byte order so you can use them immediately.

Code Snippet
 .data
sin SOCKADDR_IN <>
hostname db "members.xoom.com",0
Port dd 80                    ; We use port 80, HTTP port for demonstration purpose

.data?
socket dd ?

.code
........
mov sin.sin_family, AF_INET
invoke htons, Port                    ; convert port number into network byte order first
mov sin.sin_port,ax                  ; note that this member is a word-size param.
invoke gethostbyname, addr hostname
mov eax,[eax+12]                ; move the value of h_list member into eax
mov eax,[eax]                      ; copy the pointer to the actual IP address into eax
mov eax,[eax]                      ; copy IP address into eax
mov sin.sin_addr,eax
invoke connect,socket,addr sin,sizeof sin
.if eax==SOCKET_ERROR            ; assuming we use non-blocking mode, connect
                                                            ; will always return SOCKET_ERROR
    invoke WSAGetLastError            ; retrieve the actual error code
    .if eax!=WSAEWOULDBLOCK        ; if it's not WSAEWOULDBLOCK
        <put your error handling code here>        ; it means a true error occurred
    .endif
.endif

send PROTO socket:DWORD, buffer:DWORD, len:DWORD, flags:DWORD

MSG_DONTROUTE : specifies that the data should not be subject to routing. Notice the word "should". Some windows socket implementation may ignore this flag.
MSG_OOB : specifies that the data is out-of-band data.

Normally we don't use any of these two flags, flags parameter should be 0 in this case.

Comment
This function sends data to the connected remote socket. It neither cares nor knows about the data it sends.

Code Snippet

.data?
buffer db 100 dup(?)
....
.code
.....
invoke send, socket, buffer, 100, 0
.if eax==SOCKET_ERROR
    <put your error handling code here>
.else
    .....
.endif

recv PROTO socket:DWORD, buffer:DWORD, len:DWORD, flags:DWORD

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. This flag is usually used when FD_OOB notification is received.

Comment
This function reads the data from the socket and stores them in the specified buffer.A question arises: how do you know how many bytes are available for read from the socket? The answer is the function ioctlsocket. It has the following syntax:

ioctlsocket PROTO socket:DWORD, cmd:DWROD, lpArgument:DWORD

Return Value
If successful, the return value in eax is NULL. Otherwise the value SOCKET_ERROR is returned and you may call WSAGetLastError to retrieve the error code.

Comment
This function is used to control the mode of a socket. With FIONBIO command, it can switch the socket into blocking or non-blocking mode. With FIONREAD command, it returns the amount of data available in the socket. With SIOCATMARK command, it checks whether or not all out-of-band data has been read.

Code Snippet

.data?
socket dd ?
hMemory dd ?                ; handle to memory block
buffer dd ?                       ; address of the memory block
available_data dd ?        ; the amount of data available from the socket
actual_data_read dd ?    ; the actual amount of data read from the socket
.....
.code
.....
    invoke ioctlsocket, socket, FIONREAD, addr available_data
    .if eax==NULL
        invoke GlobalAlloc, GHND, available_data
        mov hMemory,eax
        invoke GlobalLock, eax
        mov buffer,eax
        invoke recv, socket, buffer, available_data, 0
        mov actual_data_read, eax
        .....
        <use the data in buffer>
        ....
        invoke GlobalUnlock, buffer
        invoke GlobalFree, hMemory
    .endif

closesocket PROTO socket:DWORD

Return Value
If successful, it returns NULL. Otherwise SOCKET_ERROR is returned and you may call WSAGetLastError to retrieve the error code.

Comment
This function closes a socket. Every resource of the socket will be released.

Code Snippet

.data?
socket dd ?
....
.code
....
invoke closesocket, socket
.if eax==SOCKET_ERROR
    <put your error handling code here>
.else
endif

WSACleanup PROTO

Return Value
If successful, it returns NULL. Otherwise it returns SOCKET_ERROR.

Comment
There must be matching number of WSAStartup and WSACleanup calls. Say, if you call WSAStartup three times, you must also call WSACleanup three times as well else the winsock library will not be able to free any unused resource. This is the last function that you call when you're through with the winsock library.

Code Snippet

.code
.....
invoke WSACleanup
.if eax==SOCKET_ERROR
    <put your error handling code here>
.else
.endif