IPv6 Programming on Windows Tutorial

Microsoft Visual Studio .NET 2003 is a commercial product, however, the C/C++ compiler part of this product is released free from Microsoft.  You can obtain the Microsoft Visual C++ Toolkit 2003 from the URL below:

http://msdn.microsoft.com/visualc/vctoolkit2003/

Please note that the tools provided at this site are command line tools only. The GUI Integrated Development Environment (IDE) isn’t included.  Please also note that they come only with the bare minimum headers and libraries related to the language specifications.  So, it means that you won’t be able to create exactly the same environment as Microsoft Visual Studio .NET 2003.  In this series, I will provide sample code that can be compiled and tested by using Microsoft Visual C++ Toolkit 2003 as much as possible, but there may be some code that cannot be complied with the free tools.

Testing the compiler

Please download the code that will be inserted within the {getv6addr.c} listing.  In order to compile it, open a command prompt and insert the c1command as shown in the figure {Compiling getv6addr.c and example}.

getv6addr.exe is a program that finds the IPv6 address for the host name passed in as an argument.  Please give a host name to the binary that was created by compiling, and execute it.  The sample execution in the bottom of the figure {Compiling getv6addr.c and example} shows the IPv6 address for the host www.ipv6style.jp after obtaining it.

In order to use the WinSock API for IPv6 programming, include the two headers shown below:

 #include ‹winsock2.h›
 #include ‹ws2tcpip.h›

The {getv6addr.c} listing also includes winsock2.h and ws2tcpip.h.  When using Berkeley sockets in a UNIX environment, it is common practice to include the headers shown below at the beginning of the source code.

 #include ‹sys/types.h›
 #include ‹sys/socket.h›
 #include ‹netdb.h›

   cl getv6addr.c ws2_32.lib
                  ^^^^^^^^^^ 

This library contains the API entry point, and you always need to link it when you use the WinSock2 API.  (see endnote 1)

The general flow of the getv6addr.c program is shown below.

In block (2), iterate through the ADDRINFO structure list that was returned by getaddrinfo( ) using a for statement.  For each one, the binary IPv6 address (binary network format) is converted to a character string (presentation format).  The API which is used here is the getnameinfo( ) function.  The result of the character string conversion will be stored in v6addr.  The primary role of the getnameinfo( ) function is finding the host name from an IP address (reverse lookup), however, it can convert a binary representation to a character string as well.  (see endnote 2)

The four APIs that I used, which are getaddrinfo( ), getnameinfo( ), freeaddrinfo( ), and gai_strerror( ), are important APIs that can be used in many programs regardless of the server/client OS.  RFC 3493 defines how to use them, and they can be used on most of the IPv6 ready OSs although there are some restrictions and differences from system to system.  I have only outlined those functions this time.  I will explain the details of the related data structure (ADDRINFO structure) and the meaning of the arguments in the next article.

The integer types that are frequently used in Windows programming are WORD and DWORD types.

    WORD and DWORD Types in 32-bit Environment
   type | typedef defined as |        meaning
  ------+--------------------+-------------------------
  WORD  |    unsigned short  | unsigned 16-bit integer
  DWORD |    unsigned int    | unsigned 32-bit integer

  MAKEWORD(a, b) = b * 16 + a

In the {getv6addr.c} listing, there is a line MAKEWORD(2, 2).  This is a macro that creates a 16-bit WORD integer and is very often used when designating the WinSock version.  So, MAKEWORD(2, 2) = 0x0202.  In the WORD value that is created by this macro, the first argument is the least significant byte and the second argument is the most significant byte.  e.g. MAKEWORD(0x03, 0x04)=4*16+3=67.  Please be careful about the order of the arguments.

### Representation of structure and pointer types

In Windows programming, not just WinSock, there is a custom that structure and pointer types are written in all caps.  An example is shown below.

     Definition of Structure Type
   Type      | typedef defined as
  -----------+-----------------------
  ADDRINFO   | struct addrinfo
  PADDRINFO  | struct addrinfo *
  LPADDRINFO | struct addrinfo FAR *

WinSock version and initialization

WinSock version

Features in the WinSock API differ largely from version to version.  Version 1.1 supports only TCP/IP (IPv4) and is included with Windows 95 and OSs before that.  Windows NT/98 and above come with WinSock 2 by default.  It has been made multi-protocol so that it can support not only TCP/IP but multiple protocols as well.  It also supports access models such as overlapped I/O.  For IPv6 programming, designate version 2.2.

Initializing WinSock

In the {getc6addr.c} listing, there is a variable wsaData of WSADATA type, and there are also functions WSAStartup( ), which refers to the variable, and WSACleanup( ).  These are extensions unique to Windows that do not exist in Berkeley sockets.  For WinSock, initialization (WSAStartup( ) ) and shut down (WSACleanup( ) ) are always needed before you use any of the socket APIs.

For the first argument of WSAStartup( ), designate the WinSock version that is required by the program.  If version 2.2 is required, designate MAKEWORD(2, 2) (0x0202 in hexadecimal integer value).  For the WSAStartup( ) function, if the return value is 0, startup was successful (the  required WinSock version can be used), and if it failed, values other than 0 are returned.  When the function returns, the WinSock version that can be used is filled in to the lpWSAData structure that was passed in as the second argument.  By checking the contents of the lpWSAData structure, you will be able to learn about the WinSock version that comes with the OS.

In the {getc6addr.c} listing, the WSACleanup( ) function is called when the program ends.  This is a function that shuts down WinSock.

References

[1]  Hagino, Junichiro. Translated by Ogawa, Ayako. IPv6 Network Programming, ASCII, April 2003.

[2]  Ookawa, Makoto. “How to upgrade WinSock application to support IPv6.” IPv6style July 2003. Impress. <http://www.ipv6style.jp/en/apps/20030711/index.shtml>.

[3]  Napper, Lewis. Translated by Emura, Yutaka. WinSock 2 Programming, Revised, 2nd edition, Soft Bank Publishing, January 2005.

1.  For WinSock version 1.1, use wsock32.lib as the import library.  For IPv6 programming, since the use of WinSock2 is assumed, please link in ws2_32.lib.  As for the WinSock version, please refer to the section, “WinSock version”.

2.  For converting the representation, on UNIX (Free BSD/Linux/etc.), you can also use the inet_ntop( )/inet_pton( ) functions, and in the WinSock API, you can use the WSAAddressToString( )/WSAStringToAddress( ) functions.