Iczelion's Guide to Winsock Programming

Winsock or windows socket takes the concept from Unix. The idea behind sockets is to use them as communication devices between different machines in the network. Each machine can create one or more sockets to connect to other machines. Sockets make uses of TCP/IP protocol as such, it operates in the higher network layers. We use sockets in any higher protocol that wants to use TCP/IP as its transport media such as HTTP,FTP and so on. The socket itself doesn't understand or care about the content that passes through it. It just does its job of sending and receiving data to from its remote counterpart.

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:

Initialize winsock dll
Create socket
Specify the operation mode: blocking or non-blocking
Connect the socket
Perform some tasks with the socket such as sending or receiving data
Close the socket
Release winsock dll

We will explore these steps in some detail.

Socket Library Initialization You must call WSAStartup to initialize the winsock dll before using any winsock function. This function has the following syntax:

WSAStartup PROTO wVersionRequired:DWORD, LPWSADATA:DWORD

Parameters
wVersionRequried == The winsock version your application wants to use. At this time, version 1.1 and 2 are available. Version 1.1 ships with Windows 95 and version 2.x comes with Windows NT 4.0. If you want to specify version 1.1, use 101h if you want to use version 2.0, use 200h
lpWSADATA == Pointer to WSADATA structure that the winsock dll will fill in. This structure contains implementation details of the current winsock dll. Normally, you just create an uninitialized instance of WSADATA and pass its address to WSAStartup.

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 Creation After the successful WSAStartup call, you can proceed to create the socket.

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

Parameters
af == Address format which at the current time there is only one: PF_INET
type == type of the socket you want to create, stream or datagram one. If you want a stream socket, use SOCK_STREAM else use SOCK_DGRAM
protocol == if the af param is AF_UNSPEC (unspecified), you must specify the protocol here. However, since we always use PF_INET, you can use 0.

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

.if eax!=INVALID_SOCKET

mov sock,eax

.else

invoke WSAGetLastError

...

.endif

Specifying Socket Options After the socket is created, it defaults to blocking mode. If you want it to operate in non-blocking mode, you have to set that with setsockopt or WSAAsyncSelect. Normally, you should use WSAAsyncSelect to turn on non-blocking mode for the socket. So we'll demonstrate the use of WSAAsyncSelect here. setsockopt is not hard to use, you can figure it out yourself. setsockopt can alter many characteristics of a socket so you may want to look at it later.

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

Parameters
socket == socket descriptor that is returned from socket call.
hwnd == handle to the window that will receive notification of winsock events.
msg == custom windows message that you create and want the winsock library to send to your window in case the events you're interested in occur.
Event == winsock events your application is interested in. You can specify one of the constant below or add them together if your application is interested in more than one winsock event.

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

setsockopt

ioctlsocket

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

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

Connection to a Remote Socket After the socket is created, you have two choices: wait for an incoming connection or connect to a remote socket. If you want to wait for incoming connection, you must call listen to listen for an incoming connection and call accept to establish connection with the remote socket. If you want to connect to a remote socket, you must call connect which has the following syntax:

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

Parameters
socket == socket descriptor of the local socket. You can pass the socket descriptor returned by socket call as this parameter.
lpSockAddr_in == a pointer to a SOCKADDR_IN structure which is declared as follows:

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.

namelen == the size of SOCKADDR_IN structure

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.

Code Snippet

.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

If you only got URL string such as "http://members.xoom.com/Iczel", you must parse the string for the host name, in this case "members.xoom.com". And pass the address of the host name as a parameter to gethostbyname function which has the following syntax:

gethostbyname PROTO lphostname:DWORD

Parameters
lphostname == pointer to the host name string.

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

Note that in windows.inc supplied by hutch, hostent structure is named hostentStru.

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.

Comment
This function is used to retrieve the IP address(es) of the host specified as a string. Notice that what you want mostly is in h_list member.

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

Operations on the Socket There are several operations you can perform on the socket such as sending or receiving data. We'll examine both of them in detail. Sending Data to the Remote Socket We use send to send data on a stream socket and sendto to send data on a datagram socket. I'll examine send here since many popular protocols such as HTTP and FTP use stream sockets.

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

Parameters
socket == socket descriptor
buffer == address of the data that you want to send. The data need not be NULL-terminated since its size is specified in len parameter.
len == the size of data to send
flags == flags specifying the behavior of the function. There are two flags you can use:

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.

Return Value
If the call is unsuccessful, the value SOCKET_ERROR is returned in eax. If it's successful, the actual number of bytes sent is returned in eax. Note that this number may not be equal to len parameter.

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

Reading Data from the Socket There are two variants of the winsock call to read data from the socket: recv and recvfrom. recv is for use with a stream socket while recvfrom is for a datagram socket.

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

Parameters
socket == socket descriptor
buffer == address of the memory block to store the incoming data.
len == the size of the memory block
flags == flags specifying the behavior of the function. There are two flags you can use:

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.

Return Value
If the call is successful, it returns the number of bytes read from the socket. If it is unsuccessful, the value SOCKET_ERROR is returned. If the return value is 0, the remote socket has been closed.

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

Parameters
socket == socket descriptor
cmd == the command to perform on socket. There are three commands: FIONBIO, FIONREAD, and SIOCATMARK. Since we want to get the size of data available in the socket, we will focus on FIONREAD. FIONREAD command determines the amount of data which can be read from the socket. The amount of data is stored at the location pointed to by lpArgument.
lpArgument == address of an additional parameter for cmd.

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

Closing the Socket After you are finished with using the socket, you should close it by calling closesocket.

closesocket PROTO socket:DWORD

Parameter
socket == socket descriptor

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

Release Winsock Library When the application doesn't need to use winsock library anymore, it calls WSACleanup.

WSACleanup PROTO

Parameter
This function takes no parameter.

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

[Iczelion's Winsock Section][Iczelion's Win32 Assembly Homepage]