Network programming for microsoft windows 2ed

Copyright © 2002 by Microsoft Corporation PUBLISHED BY Microsoft Press A Division of Microsoft Corporation One Microsoft Way Redmond, Washington 98052-6399 Copyright ÿý 2002 by Anthony Jones All rights reserved No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher Library of Congress Cataloging-in-Publication Data Jones, Anthony, 1973Network Programming for Microsoft Windows / Anthony Jones, Jim Ohlund. 2nd ed p cm Includes index ISBN 0-7356-1579-9 Internet programming Microsoft Windows (Computer file) I Ohlund, Jim, 1966II Title QA76.625 J65 2002 005.2'768 dc21 2001058715 Printed and bound in the United States of America QWT Distributed in Canada by Penguin Books Canada Limited A CIP catalogue record for this book is available from the British Library Microsoft Press books are available through booksellers and distributors worldwide For further information about international editions, contact your local Microsoft Corporation office or contact Microsoft Press International directly at fax (425) 936-7329 Visit our Web site at www.microsoft.com/mspress Send comments to mspinput@microsoft.com Microsoft, Microsoft Press, MS-DOS, Visual Basic, Visual C++, Visual C#, Win32, Win64, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries Other product and company names mentioned herein may be the trademarks of their respective owners The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred Acquisitions Editor: David Clark Project Editor: Kurt Stephan Body Part No X08-68161 Dedication For my loving wife, Genevieve, thanks for your patience and understanding -A.J For Samantha -J.O Acknowledgments In addition to all the people who contributed to the first edition, we would like to thank the following individuals for their generous help in writing this edition Very special thanks go to Jory Prather for verifying the code samples as well as fixing them for consistency Thanks to Dave Thaler, Brian Zill, and Rich Draves for clarifying our IPv6 questions, Mohammad Alam and Rajesh Peddibhotla for help with reliable multicasting, and Jeff Venable for his contributions on the Network Location Awareness functionality Thanks to Vadim Eydelman for his Winsock expertise And finally we would like to thank the NET Application Frameworks team (Lance Olson, Mauro Ottaviani, and Ron Alberda) for their help with our questions about NET Sockets Introduction Welcome to Network Programming for Microsoft Windows, Second Edition! The second edition covers the same topics as the first edition and even more as well This book primarily focuses on the Winsock network programming technology In particular, we've added a chapter on writing high-performance, scalable Winsock applications and a chapter devoted to Winsock programming in the C# programming language using the exciting new NET Application Frameworks library In addition, we've completely updated the chapter on the Windows Service Provider Interface (SPI), and we cover additional protocols (such as IPv6 and reliable multicasting) and reveal functionality that is new to Windows XP This book covers a wide variety of networking functions available in Windows 95, Windows 98, Windows Me, Windows NT 4.0, Windows 2000, Windows XP, and Windows CE The majority of the text covers intermediate and advanced networking topics, but we retooled the Winsock section so that it is more accessible to programmers of all levels How to Use This Book This book covers six technical areas: Winsock application programming interface (API) NET Sockets (from C#) Visual Basic Winsock Control Client Remote Access Server (RAS) IP Helper API Legacy Networking—NetBIOS and the Windows redirector The NetBIOS and Windows redirector technologies have not changed since the first edition, and because of space considerations, these chapters are included only with the eBook located on the companion CD-ROM as Chapters 17-22 In this edition, the majority of the book is dedicated to covering the Winsock API Chapter starts with an introduction to Winsock and is specifically geared for the beginning Winsock programmer This chapter covers all the basics and introduces Transmission Control Protocol (TCP) and User Datagram Protocol (UDP) through simple samples, as well as providing a roadmap to advanced Winsock topics covered in other chapters For the sake of simplicity, Chapter covers the IPv4 protocol Chapter discusses the Winsock architecture such as the Winsock catalog, as well as how Winsock fits into the overall network stack In addition, we cover how to enumerate the Winsock catalog and find characteristics specific to each protocol installed on the system Chapter is dedicated to the Internet Protocol (IP) In this chapter we cover both IPv4 and IPv6 and include addressing information and name resolution for each The last part of this chapter illustrates how to write applications that work seamlessly over either protocol The remaining protocols accessible from Winsock are covered in Chapter In both chapters, we present simple samples illustrating the basic concepts of each protocol family Chapters and cover the input/output (I/O) models Winsock offers for the advanced Winsock programmer Chapter presents each model and the basics of how to use it, while Chapter goes into detail on how to write high-performance, scalable Winsock applications In this chapter, we discuss resource management and the merits of the different I/O models as well as performance numbers Sample code is provided that illustrates each of the I/O models Chapter is a reference that covers all the socket options and ioctls that can be accessed from Winsock These include generic Winsock options as well as protocol-specific ioctls For each option, we provide the expected input and output parameters necessary for successfully accessing the option This chapter has been updated to include options specific to new protocols (such as IPv6 and reliable multicasting) Chapter covers Winsock registration and name resolution and introduces the different name spaces in which queries can be performed, such as Domain Name System (DNS), Service Advertising Protocol (SAP), and the Active Directory directory service The chapter also discusses the new Network Location Awareness (NLA) namespace, which can provide valuable information about the network you are currently connected to Multicasting is the topic of Chapter This chapter covers IPv4 and IPv6 multicasting as well as the reliable multicasting transport new to Windows XP This chapter also discusses ATM point-to-multipoint communications Chapter 10 is devoted to Quality of Service (QOS), which is a technology that allows for guaranteeing a portion of the network bandwidth to an application Chapter 11 moves on to raw IP sockets and discusses how to build your own protocol headers which can be used to communicate directly over IP networks—this includes both IPv4 and IPv6 Chapter 12 covers the Winsock Service Provider Interface (SPI) This interface is a means by which a programmer can install a layer between Winsock and lower-level service providers such as Transmission Control Protocol/Internet Protocol (TCP/IP) for the purpose of manipulating socket and protocol behavior or name registration and resolution This is an advanced feature that allows software developers to extend Winsock functionality The SPI chapter has been completely rewritten and provides fully functioning, robust layered service provider (LSP) sample code Chapter 13 covers the NET Application Framework's Network Socket object In this chapter, we show how to access the new Socket class from the C# language Chapter 14 discusses the Microsoft Visual Basic Winsock control We decided to include this chapter after seeing how many developers rely on Visual Basic and this control The control is limited in its ability to utilize the advanced features of Winsock, but it is fantastic for Visual Basic developers who require simple, easy-to-use network communication Chapter 15 covers the Remote Access Server (RAS) client API We decided to include a chapter on RAS because of the popularity of the Internet, dial-up communication, and Virtual Private Networking (VPN) communication The ability for a programmer to add dial-up capability to a network application is quite useful since it makes the program easier for the user That is, an end user does not need to know how to set up and establish a dial-up connection to use your network application Chapter 16 covers the IP Helper API, which provides useful information about the network configuration on the current computer This includes a new function that enumerates IPv6 specific information Finally, chapters on the legacy technologies (NetBIOS, mailslots, named pipes, and Windows Redirector) from the first edition, as well as NetBIOS command and Winsock error code references, are included in eBook form (as Chapters 17-22) on the companion CD-ROM We hope that you will find this book to be a valuable learning and reference tool We still believe it is the most comprehensive book about Windows network programming available How to Use the Companion CD-ROM In each chapter, we present code examples that demonstrate how to use many of the net-working APIs we describe These examples are available on the accompanying CD-ROM To install them, place the CD into your drive and Autorun will launch a starting menu If the starting menu does not launch automatically, it can be accessed by running StartCD.exe in the disc's root directory The sample code can be installed by selecting the Install Example Code option on the starting menu, or you can access each example from the CD (under Samples\ChapterXX) The CD-ROM requires a computer running a 32-bit Microsoft Windows platform About the eBook The companion CD-ROM also includes an electronic version of the book that you can view using Microsoft Internet Explorer 5.01 or later To Use the eBook Insert the companion CD-ROM into your CD-ROM drive On the starting menu that appears, click eBook and follow the instructions, or select Run from the Start menu and type D:\eBook\Autorun.exe (where D is the name of your CD-ROM disk drive) This will install an icon for the eBook on your desktop Click OK to exit the Installation Wizard You must have the companion CD-ROM inserted in your CD-ROM drive to run the eBook Microsoft Press Support Information Every effort has been made to ensure the accuracy of the contents of this book and the companion CD-ROM Microsoft Press provides corrections for this book at http://www.microsoft.com/mspress/support/ Many of the function definitions and tables in this book were adapted or reprinted here with the generous participation and permission of the Microsoft Platform SDK documentation group Some material is based on preliminary documentation and is subject to change For the latest Platform SDK information as well as updates and bug fixes, please visit the MSDN Web site at http://www.microsoft.com/msdownload/platformsdk/sdkupdate/ If you have comments, questions, or ideas regarding this book or its companion CD, please send them to Microsoft Press via e-mail to: MSPInput@Microsoft.com or via postal mail to: Microsoft Press Attn: Network Programming for Microsoft Windows, Second Edition Editor One Microsoft Way Redmond, WA 98052-6399 Please note that product support is not offered through the above address Chapter Introduction to Winsock This chapter is dedicated to learning the basic techniques for writing successful Winsock applications Winsock is a standard application programming interface (API) that allows two or more applications (or processes) to communicate either on the same machine or across a network and is primarily designed to foster data communication over a network It is important to understand that Winsock is a network programming interface and not a protocol Winsock provides the programming interface for applications to communicate using popular network protocols such as Transmission Control Protocol/Internet Protocol (TCP/IP) and Internetwork Packet Exchange (IPX) The Winsock interface inherits a great deal from the BSD Sockets implementation on UNIX platforms In Windows environments, the interface has evolved into a truly protocol-independent interface, especially with the release of Winsock In this chapter, we'll look at the fundamentals of setting up communication from one machine on a network to another, along with how to send and receive data The examples presented in this chapter help to provide an understanding of the Winsock calls that are required for accepting connections, establishing connections, and sending and receiving data Because the purpose of this chapter is to learn these fundamental Winsock calls, the examples presented use straight blocking Winsock calls Chapter presents non-blocking and other advanced I/O methods available in Winsock, including code examples In addition, in this chapter we will present both the Winsock and Winsock versions of the various API functions You can differentiate the two functions with the WSA prefix If Winsock updated or added a new API function in its specification, the function name is prefixed with WSA For example, the Winsock function to create a socket is simply socket Winsock introduces a newer version named WSASocket that is capable of using some of the new features made available in Winsock There are a few exceptions to this naming rule WSAStartup, WSACleanup, WSARecvEx, and WSAGetLastError are in the Winsock 1.1 specification Before you begin developing an application using Winsock, you need to understand what files and libraries are required to build your application NCBDGSENDBC This command sends a broadcast datagram to every host on the LAN Only those machines with an outstanding receive datagram command get the message Also, if the local adapter has a pending receive datagram command, it receives its own message Broadcast datagrams have the same size limitation mentioned in the NCBDGSEND entry Table 22-12 describes the characteristics of the NCBDGSENDBC command Table 22-12NCBDGSENDBC Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn ncb_num In X ncb_buffer In X ncb_length In X ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBENUM This command enumerates LANA numbers When you issue this command, set ncb_buffer to a LANA_ENUM structure On return, the length field of LANA_ENUM returns the number of LANA numbers on the local machine The lana field of LANA_ENUM is filled with the LANA numbers Table 22-13 describes the characteristics of the NCBENUM command Table 22-13NCBENUM Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn ncb_num ncb_buffer In X ncb_length In X ncb_lana_num In X ncb_cmd_cplt Out ncb_callname ncb_name ncb_rto ncb_sto ncb_post ncb_event NCBFINDNAME This command finds the location (machine name) of a name on the network When this command is issued, ncb_buffer is filled with a FIND_NAME_HEADER structure, followed by one or more FIND_NAME_BUFFER structures This command is Microsoft Windows NT–specific and is not supported on any other Windows platforms Table 22-14 describes the characteristics of the NCBFINDNAME command Table 22-14NCBFINDNAME Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn ncb_num ncb_buffer In/Out X ncb_length In X ncb_callname In X ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBHANGUP This command closes a specified connected session All pending receive commands for the session are terminated and return the “session closed” error message, NRC_SCLOSED (0x0A) If either send or chain send commands are outstanding, the hang up command delays until the command completes This delay occurs whether the commands are transferring data or waiting for the remote side to issue a receive command Additionally, if multiple outstanding NCBRECVANY commands exist, only one of them returns an error code when the session is closed For any other receive command, each outstanding receive returns an error Table 22-15 describes the characteristics of the NCBHANGUP command Table 22-15NCBHANGUP Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn In X ncb_num ncb_buffer ncb_length ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBLANSTALERT This is a Windows NT–only command that notifies the user of LAN failures that last for more than one minute However, in testing, this command did nothing in response to several common LAN failures, such as disconnected network cables Table 22-16 describes the characteristics of the NCBLANSTALERT command Table 22-16NCBLANSTALERT Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn ncb_num ncb_buffer ncb_length ncb_callname ncb_name ncb_rto ncb_sto ncb_post ncb_lana_num In ncb_cmd_cplt Out ncb_event X NCBLISTEN This command listens for a connection from another process, local or remote If the first character of ncb_callname is an asterisk (*), a session is established with any network adapter that issues an NCBCALL to the local name The name making the NCBCALL is returned in the ncb_callname field If either a send or receive timeout is specified, these timeout values are applied to all send and receive calls made on the new session Table 22-17 describes the characteristics of the NCBLISTEN command Table 22-17NCBLISTEN Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn Out ncb_num ncb_buffer ncb_length ncb_callname In/Out X ncb_name In X ncb_rto In ncb_sto In ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBRECV This command receives data from the specified session name If more than one command capable of receiving data is pending, they are processed in the following order: Receive (NCBRECV) Receive-any for a specified name (NCBRECVANY) Receive-any for any name (NCBRECVANY) All commands with the same precedence are processed in first-in, first-out (FIFO) order If the buffer passed is not large enough to hold the data, the error NRC_INCOMP (0x06) is returned If this occurs, issue another receive command with a larger buffer unless the send command was issued with either a timeout that expired or a no-ack—in which case the data is lost The ncb_length field is set to the amount of data actually read on return Table 22-18 describes the characteristics of the NCBRECV command Table 22-18NCBRECV Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn In X ncb_num In X ncb_buffer In X ncb_length In/Out X ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBRECVANY This command receives data from any session corresponding to the specified name This command can also be used to receive data destined for any local name by setting the ncb_num field to 0xFF Otherwise, simply set ncb_num to the network number returned from adding a name to the local name table Then any data pending for that particular name will be picked up by this command Also, a precedence order exists for when multiple receive commands are outstanding See the entry for NCBRECV for more details When a session is closed by a local session close command, by the remote side closing the session, or by a session abort command, any outstanding NRCRECVANY commands for the specified name complete with the error NRC_SCLOSED (0x0A); the ncb_lsn field of the NCB structure is set to the local session number that was terminated If no NCBRECVANY commands for that closed session are pending for the specified name and an outstanding NCBRECVANY command exists for any session (ncb_num is 0xFF), that command completes with the error NRC_SCLOSED and with the ncb_lsn field set to the corresponding session number Table 22-19 describes the characteristics of the NCBRECVANY command Table 22-19NCBRECVANY Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn Out ncb_num In/Out X ncb_buffer In X ncb_length In/Out X ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBRESET This command resets the specified LANA number and affects certain environment resources as follows: If ncb_lsn is not 0, all resources associated with ncb_lana_num are freed If ncb_lsn is 0, all resources associated with ncb_lana_num are freed and new resources are allocated The ncb_callname[0] byte specifies the maximum number of sessions, the ncb_callname[2] byte specifies the maximum number of names, and the ncb_callname[3] byte requests that the application use the computer's name (which has the name number 1) Table 22-20 describes the characteristics of the NCBRESET command Table 22-20NCBRESET Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn In X ncb_num In X ncb_lana_num In X ncb_cmd_cplt Out ncb_buffer ncb_length ncb_callname ncb_name ncb_rto ncb_sto ncb_post ncb_event NCBSEND This command sends data to the specified session partner The maximum data size that can be transmitted is 65,536 bytes (64 KB) If the remote side issues a hang up command, all pending sends return the “session closed” error, NRC_SCLOSED (0x0A) If more than one send command is pending, they are processed in FIFO order Table 22-21 describes the characteristics of the NCBSEND command Table 22-21NCBSEND Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn In X ncb_buffer In X ncb_length In X ncb_num ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBSENDNA This command sends data to a specified session and does not wait for acknowledgment from the session partner Otherwise, the behavior of this command is the same as that of NCBSEND Table 22-22 describes the characteristics of the NCBSENDNA command Table 22-22NCBSENDNA Field In/Out Required ncb_command In ncb_retcode Out ncb_lsn In X ncb_buffer In X ncb_length In X ncb_num ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBSSTAT This command retrieves the status of a session When calling this command, ncb_buffer is set to a block of memory that is filled with a SESSION_HEADER structure followed by one or more SESSION_BUFFER structures If the first byte of ncb_name is an asterisk (*), this command obtains the status for all sessions associated with all names in the local name table If the supplied buffer is too small, the error NRC_INCOMP (0x06) is returned If the buffer length is less than 4, the error returned is NRC_BUFLEN (0x01) Table 22-23 describes the characteristics of the NCBSSTAT command Table 22-23NCBSSTAT Field In/Out Required ncb_command In X ncb_retcode Out ncb_lsn ncb_num Out ncb_buffer In X ncb_length In X In X ncb_callname ncb_name ncb_rto ncb_sto ncb_post In ncb_lana_num In ncb_cmd_cplt Out ncb_event In X NCBUNLINK This command unlinks the adapter and is provided for compatibility with earlier versions of NetBIOS It has no effect on Windows platforms About the Authors Anthony Jones Anthony Jones was born in San Antonio, Texas, and graduated with honors from the University of Texas at San Antonio in 1996 with a bachelor's degree in computer science His undergraduate thesis was based upon optimizing the Icon compiler After graduation, Anthony worked for Southwest Research Institute, a nonprofit contract research company in San Antonio There he worked on a variety of projects, including real-time embedded control systems and visualization and simulation software, for customers ranging from the U.S Air Force to the Weather Channel In 1997, he moved to Washington State to work for Microsoft Developer Support on the NetAPI team Anthony recently moved to the Windows 2000 Core Networking department, where he is a tester on the Winsock team In his spare time, Anthony enjoys mountain biking, skiing, hiking, photography, and watching Futurama and The X-Files Jim Ohlund Jim Ohlund works as a software design engineer for Microsoft's Internet Security and Acceleration (ISA) Server test team in Redmond, Washington He has worked in many areas of the computer industry, from systems programming to developer support to software testing In 1990, Jim received a bachelor's degree in computer science from the University of Texas at San Antonio Jim began his computer career while still in college by developing personnel systems for the United States Department of Defense He expanded his working knowledge of computer networks and network programming in 1994 by developing terminal emulation software for Windows platforms In 1996, Jim joined Microsoft's Developer Support Networking API team, helping software developers use many of the networking APIs described in this book When Jim is not working with computers, he likes to ski, snowboard, bicycle, and hike in the beautiful Pacific Northwest ... of networking functions available in Windows 95, Windows 98, Windows Me, Windows NT 4.0, Windows 2000, Windows XP, and Windows CE The majority of the text covers intermediate and advanced networking... Versions Platform Winsock Version Windows 95 1.1 (2.2) Windows 98 2.2 Windows Me 2.2 Windows NT 4.0 2.2 Windows 2000 2.2 Windows XP 2.2 Windows CE 1.1 Note that even though a platform supports... Microsoft Press via e-mail to: MSPInput @Microsoft. com or via postal mail to: Microsoft Press Attn: Network Programming for Microsoft Windows, Second Edition Editor One Microsoft Way Redmond, WA 98052-6399