TEAMFLY

and
John C. Penman
Wordware Publishing, Inc.
Library of Congress Cataloging-in-Publication Data
Moore, Alan C., 1943
The Tomes of Delphi : basic 32-bit communications programming / by Alan C. Moore
and John C. Penman.
p. cm.
Includes bibliographical references and index.
ISBN 1-55622-752-3 (paperback)
1. Computer software—Development. 2. Delphi (Computer file). 3. Telecommunication
systems. I. Penman, John C. II. Title.
QA76.76.D47 M665 2002
005.1 dc21 2002011
CIP
© 2003, Wordware Publishing, Inc.
All Rights Reserved
2320 Los Rios Boulevard
Plano, Texas 75074
No part of this book may be reproduced in any form or by
any means without permission in writing from
Wordware Publishing, Inc.
Printed in the United States of America
ISBN 1-55622-752-3
10987654321
0210
Delphi is a registered trademark of Borland Software Corporation in the United States and other countries. Other products
mentioned are used for identification purposes only and may be trademarks of their respective companies.
All inquiries for volume purchases of this book should be addressed to Wordware Publishing, Inc., at the above
address. Telephone inquiries may be made by calling:

Conditional Acceptance 12
Connect and Disconnect Data 12
Socket Sharing 12
Protocol-specific Addition 12
Socket Groups 12
Summary 13
Chapter 2: Winsock Fundamentals 15
Starting and Closing Winsock 15
function WSAStartup 16
function WSACleanup 19
Handling Winsock Errors 22
Errorsanderrors 23
function WSAGetLastError 24
procedure WSASetLastError 25
v
The Many Faces of the Winsock DLL 27
Summary 28
Chapter 3: Winsock 1.1 Resolution 29
Translation Functions 30
function htonl 31
function htons 32
function ntohl 32
function ntohs 33
Miscellaneous Conversion Functions 34
function inet_addr 34
function inet_ntoa 35
Resolution 37
Resolving Using a HOSTS file 38
Resolving Using DNS 39
Resolving Using a Local Database File with DNS 40

function WSAStringToAddress 78
Enumerating Network Protocols 79
function WSAEnumProtocols 86
Name Space Resolution and Registration 87
Enumerating Name Spaces 88
function WSAEnumNameSpaceProviders 89
Registering a Service 91
function WSAInstallServiceClass 95
function WSASetService 102
function WSARemoveServiceClass 102
Service Queries 103
function WSALookupServiceBegin 105
function WSALookupServiceNext 109
WSALookupServiceEnd 112
Helper Functions 112
function WSAGetServiceClassInfo 112
function WSAGetServiceClassNameByClassId 113
Functions for the Future 115
Making Your Winsock Applications Agnostic 116
function getaddrinfo 119
procedure freeaddrinfo 126
function getnameinfo 126
function gai_strerror 132
Obsolete Functions 132
Summary 133
Chapter 5: Communications 135
The Mechanics of Data Exchange 136
Socket Creation 137
function socket 141
function WSASocket 143

I/O Schemes 183
Using Select 183
Using WSAAsyncSelect 185
Using WSAEventSelect 188
Using Overlapped Routines 191
Event Notification 192
Completion I/O Schemes 193
Completion Port I/O Scheme 194
Which I/O Scheme to Use? 195
To Block or Not to Block? 196
Winsock and Multithreading 198
function select 203
function WSAAsyncSelect 203
function WSACreateEvent 210
function WSAWaitForMultipleEvents 215
function WSAEnumNetworkEvents 220
function WSAEventSelect 221
function WSACloseEvent 222
function WSAResetEvent 222
function WSASetEvent 223
function WSAGetOverlappedResult 224
Raw Sockets 225
Microsoft Extensions to Winsock 2 239
function AcceptEx 241
procedure GetAcceptExSockaddrs 242
function TransmitFile 243
function WSARecvEx 245
Microsoft Extensions to Winsock 2 for Windows XP and
Windows .NET Server 246
function ConnectEx 247

Option = IP_TOS 273
Option = IP_TTL 273
Option = IP_MULTICAST_IF 274
Option = IP_MULTICAST_TTL 274
Option = IP_MULTICAST_LOOP 274
Option = IP_ADD_MEMBERSHIP 274
Option = IP_DROP_MEMBERSHIP 274
Option = IP_DONTFRAGMENT 274
Modifying I/O Behavior 274
function getsockopt 278
function setsockopt 279
function ioctlsocket 279
function WSAIoctl 280
Summary 281
ix
Contents
Part 2: TAPI
Chapter 7: Introduction to TAPI 285
An Historical Review 286
The World of Telephony Applications 287
The Elements of a Telephony System 290
Nature and Structure of TAPI 292
Media Stream 294
Varieties of Physical Connections 295
Levels of Telephony Programming Using TAPI 297
Summary 304
Chapter 8: Line Devices, Essential Operations 305
Stages in Working with Telephony 306
Three Notification Mechanisms 307
TAPI Line Support—Basic and Extended Capabilities 309

Contents
TEAMFLY


function lineGetID 373
function lineGetLineDevStatus 375
structure LINEDEVSTATUS 376
structure LINEAPPINFO 378
function lineGetTranslateCaps 379
function lineInitialize 380
function lineInitializeEx 382
function lineNegotiateAPIVersion 384
function lineNegotiateExtVersion 386
function lineOpen 387
function lineSetDevConfig 391
function lineShutdown 392
function lineGetCountry 393
structure LINECOUNTRYLIST 394
structure LINECOUNTRYENTRY 395
function lineGetIcon 396
function lineSetAppSpecific 397
function lineSetCurrentLocation 398
Summary 399
Chapter 9: Handling TAPI Line Messages 401
Line Callback 401
function TLineCallback 401
Issues Involving Messages 416
LINE_ADDRESSSTATE Message 417
LINE_AGENTSPECIFIC Message 418
LINE_AGENTSTATUS Message 418
LINE_APPNEWCALL Message 419
LINE_CALLINFO Message 420
LINE_CALLSTATE Message 422
LINE_CLOSE Message 426

function lineSetStatusMessages 448
function lineSetCallPrivilege 449
Chapter 10: Placing Outgoing Calls 451
Canonical and Dialable Address Formats 451
Assisted Telephony 453
TAPI Servers in Assisted Telephony 457
Assisted Telephony Functions 458
function tapiRequestMakeCall 459
function tapiGetLocationInfo 460
Establishing a Call with Low-Level Line Functions 461
Special Dialing Support 464
function lineDial 465
function lineMakeCall 466
structure LINECALLPARAMS 468
LINECALLPARAMFLAGS_ Constants 473
function lineTranslateAddress 474
structure LINETRANSLATEOUTPUT 477
function lineTranslateDialog 479
Summary 480
Chapter 11: Accepting Incoming Calls 481
Finding the Right Application 481
Unknown Media Type 483
Prioritizing Media Modes 484
Responsibilities of the Receiving Application 485
Media Application Duties 486
Accepting an Incoming Call 487
Ending a Call 493
xii
Contents
Reference for Additional Basic TAPI Functions 494

thank some of the many people who helped make it possible. First, let me thank
my wife, Ann, and daughter, Treenah, for their support and patience during the
many hours I spent in front of a computer screen coding and writing. My col
-
leagues at Kentucky State University have also been very supportive, especially
my new chairperson, Dr. Barbara Buck, who provided much encouragement for
my writing.
There are several people and one organization that had a great deal to do with
my getting involved with TAPI in the first place. The organization is Project
JEDI, which produced the translation of the TAPI header file for use in Delphi.
The pioneering work of the original translators, Alexander Staubo and Brad
Choate, was followed by the excellent new translation by Marcel van Brakel,
with contributions from Rudy Velthuis and myself.
The TAPI portion of this book is based to some extent on a series of articles I
wrote in Delphi Informant Magazine beginning in the late 1990s. Thanks to my
good friend Jerry Coffey, the editor of Delphi Informant Magazine, for his contin-
ued encouragement to explore and write about TAPI. Thanks also to Major Ken
Kyler, with whom I wrote the first three articles. Ken provided me with my first
introduction to the world of TAPI. I would be remiss if I did not acknowledge my
current co-author, John Penman. In the process of writing this book, we have
read each other’s text in some detail. Working with John on this book has been
delightful from the start. Finally, let me acknowledge my excellent technical edi
-
tor, Gary Frerking, president of TurboPower. He was extremely helpful in
identifying portions of the text that were not clear and code that needed further
work.
Before closing, I want to acknowledge the importance of my guru and spiri
-
tual teacher, the late Chogyam Trungpa, Rinpoche. The meditative disciplines
he introduced to me and so many others have helped make my life more full and

xv
Acknowledgments

Introduction
Reliable communications using computers has been important for a long time,
starting with DOS bulletin boards and the early days of the Internet. In this
book, we will provide an introduction to two of the essential communications
technologies, Windows Sockets (Winsock), the backbone of the Internet on the
Windows platform, and the Telephony Application Programming Interface
(TAPI).
We will provide a complete introduction to Winsock and basic TAPI. We had
originally planned on covering many of the other Internet technologies and the
entire TAPI, but discovered that the material was too extensive to do justice to
any of these technologies. We plan to write another book dealing with advanced
communications programming in which we will cover the more difficult and
newer topics. Nevertheless, this work should provide all that you will need to
write useful Internet/Intranet or telephony applications. The advanced book will
build on this foundation and provide the means for going beyond basic
functionality.
This book is organized into two parts. Part I, written by John C. Penman, is a
complete introduction to Winsock programming. Chapter 1 provides an intro-
duction to this technology and a description of the Winsock-related chapters
that follow. Part II, written by Alan C. Moore, is a complete introduction to basic
TAPI programming. Chapter 7 provides an introduction to this technology and a
description of the TAPI-related chapters that follow. As in other volumes in
Wordware Publishing’s Tomes of Delphi series, most chapters include introduc
-
tory sections on the various technologies, a complete reference to functions,
structures, and constants, and Delphi code examples.
The book concludes with three appendices providing a glossary of essential


ers, no file transfer, and none of the e-mail applications that we take so much for
granted in today’s Windows environment. Technologies like DCOM and n-tier
database systems would be difficult to implement.
Winsock is an API that is an integral part of Microsoft’s Windows Open Sys-
tems Architecture (WOSA), which we’ll discuss later in this chapter, as well as
in the second half of the book dealing with TAPI. Let’s start with the history of
the genesis of the Internet to the present.
In the Beginning
Nowadays, it’s easy to forget that the genesis of the Internet arose as a need for
a dependable and robust communication network for military and government
computers in the United States of America. In response to this need, in 1969
the Defense Advanced Research Projects Agency (DARPA) sponsored an exper
-
imental network called Advanced Research Projects Agency Network
(ARPANET).
Before the birth of ARPANET, for one computer to communicate with
another on a network, both machines had to come from the same vendor. We
call this arrangement a homogeneous network. In contrast, ARPANET, a collec
-
tion of different computers linked together, was a heterogeneous network.
As ARPANET developed, it became popular for connected institutions to
accomplish daily tasks such as e-mail and file transfer. In 1975, ARPANET
became operational. However, as you might have already guessed, research into
network protocols continued. Network protocols that developed early in the life
3
of ARPANET evolved into a set of network protocols called the Transmission
Control Protocol/Internet Protocol (TCP/IP) suite. The TCP/IP protocol suite
became a Military Standard in 1983, which made it mandatory for all computers
on ARPANET to use TCP/IP.
2

It is a standard implementation on every computer from PCs to
supercomputers.
n
It is used in local area networks (LANs) and wide area networks (WANs).
n
It is used by commercial entities, government agencies, and universities.
4
n
Chapter 1
The Internet’s rapid growth (and its continued growth) owes much to the devel
-
opment of the Hypertext Transfer Protocol (HTTP) that has provided the
underpinnings for the World Wide Web. Rightly or wrongly, the ordinary man
and woman on the street now sees the World Wide Web as the
Internet.
Internet protocols like HTTP, FTP, SMTP, and POP3 are high-level protocols
that operate seamlessly on top of the network protocols collectively known as
the TCP/IP protocol suite, or just TCP/IP. We’ll describe briefly the network
protocols that constitute the TCP/IP protocol suite in the next section.
Network Protocols
TCP/IP is a suite of network protocols upon which higher-level protocols, such
as FTP, HTTP, SMTP, and POP3, operate. This suite comprises the two major
protocols (TCP and IP) and a family of other protocols. We enumerate these as
follows:
n
Transmission Control Protocol (TCP) is a connection-based protocol
that provides a stable, full duplex byte stream for an application. Applica-
tions like FTP and HTTP use this protocol.
n
User Datagram Protocol (UDP) is a connectionless protocol that pro-

guide, not a specification, for the construction of any network. This guide, Open
System Interconnection (OSI), states that a network should provide seven lay
-
ers, as explained in Figure 1-1.
If we map TCP/IP using the OSI network model, we get the following simplified
diagram in Figure 1-2.
6
n
Chapter 1
Figure 1-1
Figure 1-2