This manual and the software described in it are copyrighted, with all rights reserved. Under the copyright laws, this manual or the software may not be copied, in whole or part, without written consent of Apple, except in the normal use of the software or to make a backup copy of the software. The same proprietary and copyright notices must be affixed to any permitted copies as were affixed to the original. This exception does not allow copies to be made for others, whether or not sold, but all of the material purchased (with all backup copies) may be sold, given, or loaned to another person. Under the law, copying includes translating into another language or format.
You may use the software on any computer owned by you, but extra copies cannot be made for this purpose.
The Apple logo is a registered trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws.
Apple, the Apple logo, AppleTalk, LaserWriter, LocalTalk, Macintosh, MacTCP, and MPW are trademarks of Apple Computer, Inc., registered in the United States and other countries.
Simultaneously published in the United States and Canada.
Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance of these products.
Contents
Preface: About This Guide / vii
1 Introduction / 1
Architectural overview / 2
Application, presentation, and session layers / 2
Transport layer / 3
Transmission Control Protocol (TCP) / 3
User Datagram Protocol (UDP) / 3
Network layer / 4
Data link layer / 4
Physical layer / 4
2 The MacTCP Driver / 5
The PBOpen call / 6
The PBControl call / 7
The PBClose call / 8
The Gestalt call / 8
Implementation notes / 9
Fragmentation and reassembly / 9
Routing / 9
3 User Datagram Protocol / 11
Data structures / 12
Write Data Structures / 12
Receive buffer area / 13
Using UDP / 13
UDP routines / 14
UDPCreate / 15
UDP asynchronous notification routine / 16
UDPRead / 18
UDPBfrReturn / 19
UDPWrite / 20
UDPRelease / 21
UDPMTU / 21
UDP Multiport Create / 22
UDP Multiport Send / 23
UDP Multiport Receive / 24
C parameter-block definitions / 25
4 Transmission Control Protocol / 29
Data structures / 30
Read and Write Data Structures / 30
Receive buffer area / 30
Using TCP / 31
Streams and connections / 31
Asynchronous notification routine / 31
Connection opening / 31
Receiving data / 32
Sending data / 32
Timeouts / 32
Pushed data / 33
Urgent mode / 33
Connection closing / 34
Network management information / 34
Formatting MacTCP commands / 35
TCP routines / 35
TCPCreate / 36
TCP asynchronous notification routine / 37
TCPPassiveOpen / 41
TCPActiveOpen / 44
TCPSend / 45
TCPNoCopyRcv / 47
TCPBfrReturn / 49
TCPRcv / 50
TCPClose / 52
TCPAbort / 53
TCPStatus / 54
TCPRelease / 56
TCPGlobalInfo / 57
C parameter-block definitions / 59
5 Name-to-Address Resolution / 65
The AddressXlation.h header file / 66
The OpenResolver call / 67
The StrToAddr call / 68
The AddrToStr call / 69
The EnumCache call / 70
The AddrToName call / 72
The HInfo call / 73
The MXInfo call / 74
The CloseResolver call / 75
Binding the DNR to the application / 75
DNR operation / 76
6 Miscellaneous Interfaces / 77
MacTCPCommontypes / 78
Result codes / 78
Miscellaneous types / 81
Internet Control Message Protocol report structures / 81
GetMyIPAddr / 82
ICMP echo / 83
Appendix Constants / 85
Command codes / 85
UDP asynchronous event codes / 85
TCP asynchronous event codes / 86
Reasons for TCP termination / 86
Preface About This Guide
This guide describes how to create application programs for the MacTCP driver. The MacTCP driver, Apple Computer’s implementation of the protocol suite known as Transmission Control Protocol/Internet Protocol (TCP/IP), increases the Macintosh computer’s ability to operate in a heterogeneous computer environment.
What’s in this guide
This guide is divided into six chapters and one appendix that contain the following information:
n Chapter 1, “Introduction,” provides an overview of the MacTCP architecture.
n Chapter 2, “The MacTCP Driver,” describes the PBOpen, PBControl, PBClose, and Gestalt calls and describes internal algorithms and decisions made by the driver.
n Chapter 3, “User Datagram Protocol,” describes UDP routines.
n Chapter 4, “Transmission Control Protocol,” describes TCP routines.
n Chapter 5, “Name-to-Address Resolution,” describes how textual names are resolved to IP addresses.
n Chapter 6, “Miscellaneous Interfaces,” describes the types that are found throughout the programmatic interfaces supplied with the MacTCP driver.
n The Appendix, “Constants,” presents command codes, UDP asynchronous event codes, TCP asynchronous event codes, and reasons for TCP termination.
Who should read this guide
This guide is designed both for Macintosh programmers who are not familiar with TCP/IP and for TCP/IP programmers who are not familiar with the Macintosh programming environment.
Document conventions
This document reflects the Macintosh Programmer’s Workshop (MPW) conventions for types and sizes of variables and fields.
Related documents
You might find the following reference materials useful.
n MacTCP Administrator’s Guide
n Inside Macintosh, Volumes I–VI
n Douglas Comer, Internetworking with TCP/IP, Second Edition (Prentice-Hall, 1991)
n The MacTCP driver implements protocols that conform to the following Request for Comments (RFC) and Military Standards (MIL-STD):
—RFC 768 (User Datagram Protocol)
—RFC 791, 894; MIL-STD 1777 (Internet Protocol)
—RFC 792 (Internet Control Message Protocol)
—RFC 793; MIL-STD 1778 (Transmission Control Protocol)
—RFC 826 (Address Resolution Protocol)
—RFC 903 (Reverse Address Resolution Protocol)
—RFC 950 (Internet Subnetting)
—RFC 951, 1048 (Bootstrap Protocol)
—IDEA004 (Routing Information Protocol)
—RFC 1010 (Internet Assigned Numbers)
—RFC 1034, 1035 (Domain Name Resolver)
—RFC 1060 (Assigned Numbers)
—RFC 1122 (Requirements for Internet Hosts—Communication Layers)
1 Introduction
The MacTCP driver is a software driver for the Macintosh Operating System that allows developers to create Macintosh applications for network environments that use the Transmission Control Protocol/Internet Protocol (TCP/IP). TCP/IP is a widely used industry standard for connecting multivendor computers. The TCP/IP protocol layers are fully compatible across all implementations on different hardware platforms, allowing different vendors’ computers that run TCP/IP to interoperate and share data and services.
This chapter provides an overview of the MacTCP architecture.
Architectural overview
MacTCP protocols partially conform to the International Standards Organization (ISO) Open Systems Interconnection (OSI) layers of networking functionality. Figure 1-1 shows a comparison of the OSI and MacTCP communications architecture.
Figure 1-1 MacTCP protocols and OSI network layers
The TCP/IP protocols shown in Figure 1-1 are described in the following sections.
Application, presentation, and session layers
Services in the upper-layer protocols such as the File Transfer Protocol (FTP), Telnet, and the Simple Mail Transfer Protocol (SMTP) correspond to the application, presentation, and session layers of the OSI model. As indicated in Figure 1-1, such services are typically developer products that augment the services of TCP, IP, and the User Data Protocol (UDP).
Transport layer
The TCP and UDP provide services at the transport layer of the OSI model.
Transmission Control Protocol (TCP)
The Transmission Control Protocol provides reliable transmission of data between processes. It ensures that data is delivered error free, without loss or duplication, and in sequence.
Upper-layer protocols such as Telnet pass data to TCP for delivery to peer processes. TCP encapsulates the data into segments and passes the segments to IP, which puts the segments into datagrams and passes them across the internet. TCP at the receiving end checks for errors, acknowledges error-free segments, and reassembles the segments for delivery to upper-layer protocols. If a segment is lost or damaged, it will not be acknowledged, and the sending process will retransmit.
TCP has a flow control mechanism so that computers of different speeds and sizes can communicate. When TCP at the receiving end sends an acknowledgment, it also advertises how much data it is prepared to accept on the next transmission.
User Datagram Protocol (UDP)
The User Datagram Protocol specifies how application programs send datagrams to other application programs and defines the use of UDP ports to distinguish among multiple processes in a single machine. UDP messages are encapsulated in IP datagrams for delivery.
UDP data transmission does not provide reliability. It does not provide error checking, it does not acknowledge that data has been successfully received, and it does not order incoming messages. UDP messages can be lost or duplicated or can arrive out of order.
The advantage of UDP is that the overhead associated with establishing and maintaining an error-free TCP session is avoided. Upper-layer protocols that don’t require reliability use UDP to transmit data. For instance, the domain name system uses UDP because reliability is not critical; if there is no response to a domain name query, the resolver simply retransmits.
Network layer
The Internet Protocol (IP) provides services at the network layer of the OSI model. IP is responsible for sending data across multiple networks. IP accepts segments of data from TCP or UDP, places the data in packets called datagrams, and determines the correct path for the datagrams to take. Datagrams are sent across the internet, through as many gateways as needed, until they reach the destination host.
IP provides an addressing mechanism that allows routing between networks. The header of an IP datagram contains source and destination internet addresses so that any host in a network can route a packet to a destination, either directly or through a gateway.
IP has the ability to fragment a datagram as it is transmitted across a network. Since IP can be used with many different physical network implementations that specify different sizes for physical data frames, datagrams can be fragmented to fit into a small data frame. Fragments are reassembled as they arrive at the destination.
IP is often referred to as an unreliable delivery system because it makes a best-effort attempt to deliver all datagrams, but delivery is not guaranteed (TCP guarantees delivery). It is also called a connectionless delivery system because it routes each datagram separately. When IP receives a sequence of datagrams from TCP or UDP, it routes each datagram in the sequence individually, and each datagram may travel over a different path to the destination.
Data link layer
The AppleTalk Link Access Protocol (ALAP) and Ethernet Link Access Protocol (ELAP) provide services at the data link layer of the OSI model. ALAP and ELAP provide best-effort delivery of information between devices. They provide the basic service of packet transmission between devices connected to a single physical network.
The MacTCP driver allows for the addition of other data link layers through the use of a link layer interface between the IP layer and the data link layer. This interface is described in the document Building Alternate Link Access Protocol Modules for MacTCP available in the Developer’s CD Series from the Apple Developer’s Group.
Physical layer
The MacTCP driver operates networks in which the physical layer uses the LocalTalk cable system or the Ethernet networking standard.
2 The MacTCP Driver
The MacTCP driver is a Macintosh Operating System driver that implements the Internet Protocol (IP), User Datagram Protocol (UDP), and Transmission Control Protocol (TCP). A part of the Macintosh Operating System called the Device Manager coordinates communication between applications and the MacTCP driver.
The MacTCP driver resides in the Macintosh System Folder. At startup time, the MacTCP driver registers itself with the Device Manager as .IPP.
The MacTCP driver supports the following low-level Device Manager calls:
n PBOpen
n PBControl
n PBClose
The PBOpen call
Before the application can exchange information with the MacTCP driver, the driver must be opened using the Device Manager PBOpen call, which opens the driver and returns its reference number. All subsequent calls to the driver use this reference number.
The MacTCP driver uses the INIT-31 mechanism to automatically install itself in the device table and load itself into the system heap each time the machine is restarted. At load time, all internal buffers needed by the MacTCP driver are also allocated on the system heap. These buffers are used (among other things) to hold incoming fragments awaiting reassembly and outgoing fragments following fragmentation. The amount of buffer space allocated is based on the amount of memory in the machine.
The MacTCP driver performs its initialization sequence at PBOpen time. The initialization sequence includes initializing the local network handler, setting its local address and subnet mask, verifying that this address is reasonable and unused, and starting up the internal TCP/IP/UDP protocol machinery. PBOpen returns with an error code if any step in this process fails. In almost all cases, if PBOpen fails, the driver must be reconfigured and the system then restarted to clear the problem. Very few circumstances exist where transitory problems cause PBOpen to fail.
Use the reference number returned from the PBOpen call in all subsequent PBControl calls to this drive. Also assign this value to the ioCRefNum field.
Because of the complexity of initializing the MacTCP driver, PBOpen can return errors from many parts of the system, including the Resource Manager, Device Manager, File Manager, Slot Manager, and AppleTalk driver.
The PBControl call
The Device Manager PBControl call sends control information in the following parameter block to the driver:
struct CntrlParam {
struct QElem *qLink;
short qType;
short ioTrap;
Ptr ioCmdAddr;
ProcPtr ioCompletion;
OSErr ioResult;
char *ioNamePtr;
short ioVRefNum;
short ioCRefNum;
short csCode;
short csParam[11];
}
In this parameter block csCode specifies the type of information sent. The MacTCP driver decides what to do based on the procedure number specified by csCode (the Appendix lists procedure numbers).
All UDP and TCP routines documented in this guide are implemented as Device Manager Control calls. All MacTCP routines support both synchronous and asynchronous modes.
If a synchronous call is made, the application can’t continue until the call is completed. When control is returned to the application, the result code in the parameter block is set indicating the success or failure of the call.
If the call is asynchronous, the I/O request is placed on the driver I/O queue, and control is returned to the calling program almost immediately. While requests are taken from the driver I/O queue one at a time and processed, the application is free to perform other tasks. The application has two ways of knowing when the call has been completed:
n By polling the ioResult field in the parameter block. When this value changes from InProgress to some other value, the call has been completed.
n By specifying an I/O completion routine to be called when the requested operation is complete.
The ioCompletion field in the parameter block contains a pointer to a completion routine to be executed at the end of an asynchronous call. The ioCompletion field should be NIL for asynchronous calls with no completion routine and is automatically set to NIL for all synchronous calls.
The driver uses the ioNamePtr and ioVRefNum fields internally.
Each routine description includes a parameter block format. The number next to each field name indicates the byte offset of the field from the start of the parameter block pointed to by A0. An arrow next to each parameter name indicates whether it’s an input, output, or input/output parameter:
Arrow Meaning
Æ Parameter is passed to the routine.
¨ Parameter is returned by the routine.
´ Parameter is passed to and returned by the routine.
All Device Manager Control calls return an integer result code of type OSErr in the ioResult field of the I/O parameter block. Each routine description lists all of the applicable result codes generated by the MacTCP driver, along with a short description of what the result code means.
The PBClose call
The application should not issue a PBClose call to the MacTCP driver. Because the driver can be shared by a variety of applications, once initialized, it never stops operation until the machine is restarted. PBClose returns a closeErr error code.
The Gestalt call
The Gestalt call is used to obtain MacTCP driver version information (see the chapter “Compatibility Guidelines” in Inside Macintosh, Volume VI). To make the Gestalt call, use the mtcp selector. If you are using MacTCP driver version 1.1, a value of 1 is returned in the response field of the Gestalt call. If yu are using version 1.1.1, a value of 2 is returned. If you are using version 2.0, a value of 3 is returned. A value of 0 is returned if the driver is not opened.
Implementation notes
This section describes internal algorithms and decisions made by the MacTCP driver.
Fragmentation and reassembly
The Internet Protocol (IP) has the ability to fragment a packet so that it can be sent across a network with a small maximum transfer unit (MTU). The fragments are reassembled as they arrive at the destination. Since the application developer must select the size of UDP datagrams (unlike TCP, which negotiates packet size), you should be aware of implementation limitations imposed on the size of these datagrams.
The MacTCP driver internally allocates a memory buffer in the system heap to temporarily hold all incoming fragments waiting to be reassembled and all outgoing fragments waiting to be sent. The amount of space allocated varies depending on whether 1, 2, or 4 megabytes (MB) of memory are installed. The maximum size of the packet being fragmented or reassembled depends solely on the available free space in this buffer. Because the memory pool is shared by all MacTCP users, the allowance for the maximum size of a UDPWrite packet will vary, depending on competing demands on the memory pool. A given destination can only guarantee the reassembly of a packet that is 576 bytes (including IP and UDP headers); therefore, it is possible to send a packet from the MacTCP driver that cannot be reassembled by the destination host.
Routing
The MacTCP driver supports routing through the Routing Information Protocol (RIP) and internally listens to RIP broadcasts. Because the MacTCP driver internally listens to RIP broadcasts, an attempt to create a UDP stream on local port 520 returns a duplicateSocket error.
A default gateway can be configured using the Control Panel.
3 User Datagram Protocol
The User Datagram Protocol (UDP) provides a low-overhead transaction service to allow upper-layer protocols to send datagrams between one another. UDP is datagram oriented with best-effort delivery, but it does not use acknowledgments to make sure messages are delivered to the destination, does not order incoming messages, and does not provide feedback to control the rate at which information flows between machines.
Like the Transmission Control Protocol (TCP), UDP uses port fields to specify the source and destination processes of each transaction. An optional checksum is also used.
Data structures
The UDP packet is composed of an 8-byte header, followed by up to 65,507 bytes of data. The UDP header has the following structure:
0 word source port
2 word destination port
4 word length
6 word checksum
8 variable data
Write Data Structures
To send a UDP datagram, you must format a Write Data Structure (WDS), which has the format shown in Figure 3-1. A WDS specifies a list of buffers to write in a single operation.
The simplest WDS describes a single buffer and is 8 bytes in length: a word length, a long pointer, followed by a terminating word of 0. The most complex WDS that can be used to send a UDP datagram describes 6 buffers and is 38 bytes in length.
Figure 3-1 UDP Write Data Structure
Receive buffer area
The User Datagram Protocol (UDP) does not allocate memory for storing UDP stream databases or for buffering received datagrams. Instead, you must pass UDP enough memory for these purposes in the UDPCreate call. This has two advantages:
n The buffer memory can be allocated off the application heap instead of the system heap, which is very limited.
n You have control over the buffering provided by UDP and can allocate the appropriate amount of memory for the type of application and performance level desired.
This buffer area for incoming datagrams belongs to the MacTCP driver as long as the UDP stream is open. When UDPRelease is called, this memory is returned to you and you can then reuse it or return it to the system.
Using UDP
To send or receive UDP datagrams, you must first call UDPCreate to create a UDP stream, creating a port listener for the given UDP port and passing a memory block to the UDP driver to use in buffering incoming datagrams. UDPCreate also registers an asynchronous notification routine (ASR) that UDP uses to notify you of asynchronous events associated with this UDP stream. The MacTCP driver can support 63 open UDP streams simultaneously. The RIP process always has a stream open on port 520.
To receive a UDP datagram, call UDPRead. Then, when you finish with the buffer that holds the received datagram, call UDPBfrReturn. To send a UDP datagram, call UDPWrite. When you finish using a UDP port, call UDPRelease to close the UDP stream.
Note: Use of link-level packets larger than the maximum transfer unit (MTU) on LocalTalk networks is not advised because there are several problems with these packets on Datagram Delivery Protocol-Internet Protocol (DDP-IP) gateways. The packet MTU size should be negotiated by upper-layer protocols.
UDP routines
This section describes calls to the UDP driver. Table 3-1 lists each UDP routine and its function.
Table 3-1 UDP routines
Routine Function
UDPCreate Opens a UDP stream
UDPRead Retrieves a datagram received on a UDP stream
UDPBfrReturn Returns a receive buffer to the UDP driver
UDPWrite Sends a datagram on a UDP stream
UDPRelease Closes a UDP stream
UDPMTU Returns the maximum size of UDP data that can be sent in a datagram without IP fragmentation
UDP Multiport Create Opens UDP connections on a consecutive series of ports
UDP Multiport Send Sends a datagram from a specified port
UDP Multiport Receive Receives data from a port that was created with the UDP Multiport Create command
UDPCreate
Parameter block Æ 26 word csCode =UPDCreate
¨ 28 long stream pointer
Æ 32 long pointer to receive buffer area
Æ 36 long length of receive buffer area
Æ 40 long pointer to asynchronous notification routine (ASR)
´ 44 word local UDP port
Æ 46 long user data pointer
UDPCreate opens a UDP stream. It must be called before any UDP datagrams can be sent or received on a particular UDP port. UDPCreate returns a stream pointer that must be used in all subsequent UDP calls that operate on this UDP stream.
The receive buffer area is a block of memory that you must give to the UDP driver. UDP uses this memory to buffer incoming datagrams. This block of memory belongs to UDP while the stream is open; it cannot be modified or relocated until UDPRelease is called. The minimum allowed size of the receive buffer area is 2048 bytes, but it should be at least 2N + 256 bytes in length, where N is the size in bytes of the largest UDP datagram you expect to receive. If you expect to receive datagrams that are of the physical Maximum Transmission Unit (MTU) size, make the UDPMTU call and use the returned number N to calculate memory size.
The ASR is called by UDP to notify the user of asynchronous events such as data arrival and Internet Control Message Protocol (ICMP) messages. If the routine is 0, you are not notified of asynchronous events. See the next section, “UDP Asynchronous Notification Routine,” for more information.
If the local port is 0, UDP assigns an unused local port.
The user data pointer is returned in all ASRs for the created UDP stream.
Result codes noErr no error
streamAlreadyOpen an open stream is already using this receive buffer area
invalidLength the receive buffer area is too small
invalidBufPtr the receive buffer area pointer is 0
duplicateSocket an open stream is already using this local UDP port
insufficientResources 64 UDP streams are already open
UDP asynchronous notification routine
The asynchronous notification routine (ASR), which was registered with UDP in the UDPCreate call, is called by UDP to notify you of asynchronous events relevant to a particular UDP stream.
Since this routine is called from the interrupt level, you must not allocate or return memory to the system. Also, you are not allowed to make further synchronous MacTCP calls from an ASR. The values of all registers must be preserved except registers A0–A2 and D0–D2.
The C description of the ASR is as follows:
pascal void UDPNotifyProc (
StreamPtr udpStream,
unsigned short eventCode,
Ptr userDataPtr,
struct ICMPReport *icmpMsg);
NotifyProc is passed to the UDPCreate call for use on notification of data arrival and ICMP message reception. If this method of notification is not desired, no procedure should be passed to the UDPCreate call. (Pass an ASR pointer value of NIL.) Asynchronous notification is used with the UDPRead command only. All other commands complete in a finite amount of time and can be called synchronously.
At entry, A0 contains the stream pointer, A1 contains a pointer to the ICMP report structure if the event code in D0 is ICMP received, A2 contains the user data pointer, A5 is already set up to point to application globals, and D0 (word) contains an event code.
Event codes UDPDataArrival a UDP datagram has arrived on this stream
but no UDPRead commands are outstanding
UDPICMPReceived an ICMP has been received on this stream; register A1 points to the ICMP report
An ICMP message reports an error in the processing of a datagram that was sent on a UDP stream. When an ICMP message is received, a data structure is passed up by UDP to the client to describe the received message. This data structure, called an ICMP report, has the following format:
0 long stream pointer
4 long local IP address of stream
8 word local UDP port of stream
10 long remote IP address (destination of original datagram)
14 word remote UDP port
16 word ICMP message type
18 word optional additional information
20 long optional additional information pointer
The values for the ICMP message type are as follows:
0 network unreachable
1 host unreachable
2 protocol unreachable
3 port unreachable
4 fragmentation required
5 source route failed
6 time exceeded
7 parameter problem
8 missing required option
Codes 0–3 are defined as follows:
n Net unreachable indicates that, according to the information in a gateway routing table, the network specified in the IP destination field of a UDP datagram is unreachable.
n Host unreachable indicates that a gateway determined that the host specified in the IP destination field of a UDP datagram is unreachable.
n Protocol unreachable indicates that a UDP datagram was delivered to the destination host, but UDP was not ready to receive any datagrams.
n Port unreachable indicates that a UDP datagram was delivered to the destination host, but no UDP client was listening on that particular port.
These ICMP messages may be received occasionally when the topology of the internet changes. A single destination unreachable message should not be taken too seriously; however, if several successive UDPSend commands each result in an ICMP report indicating that the destination is unreachable, the UDP client should assume that the remote host has either crashed or is no longer accessible.
The remaining codes (4–8) indicate problems in the format of the IP header on a UDP datagram. They are informational only. Since the UDP client has no access to the IP header, you cannot correct the error.
UDPRead
Parameter block Æ 26 word csCode = UDPRead
Æ 28 long stream pointer
Æ 32 word command timeout value in seconds
(0 = infinite)
¨ 34 long remote IP address
¨ 38 word remote UDP port
¨ 40 long pointer to UDP data
¨ 44 word length of UDP data
Æ 46 word reserved; must be set to 0
Æ 48 long user data pointer
UDPRead retrieves a datagram that has been received on the UDP stream defined by the stream pointer. Some number of datagrams are buffered internally within UDP even when no UDPRead commands are outstanding, so it is not necessary to keep a UDPRead command outstanding at all times. The exact number of datagrams that can be buffered within the MacTCP driver depends on the size of the receive buffer area given to MacTCP in the UDPCreate call and the size of datagrams received.
If a UDP datagram arrives on an open UDP stream and no UDPRead commands are outstanding, you are given a data arrival notification as a hint that a UDPRead command should be issued. See the section “UDP Asynchronous Notification Routine” earlier in this chapter for more information.
The command timeout period is specified in seconds. If no datagram arrives within the timeout period, the UDPRead command is completed in error. The minimum allowed value for the command timeout is 2 seconds. A zero command timeout means infinite; the UDPRead command will not be completed until a datagram arrives.
The remote IP address and remote UDP port specify the source of the datagram.
UDPRead can return successfully even though the length of UDP data is 0. This happens when a UDP packet arrives that has the passed-in value of the UDP stream’s local UDP port, but contains no data. Since the UDPSend command permits sending zero-length UDP datagrams, the UDPRead command must pass up zero-length datagrams for symmetry.
For every UDPRead command that is completed successfully and returns a nonzero amount of data, you must call UDPBfrReturn with the same stream pointer and UDP data pointer, to return the receive buffer to the UDP driver for reuse.
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
commandTimeout no data arrived within the specified period
connectionTerminated a UDPRelease command closed the UDP
UDPBfrReturn
Parameter block Æ 26 word csCode = UDPBfrReturn
Æ 28 long stream pointer
Æ 40 long pointer to UDP data
Æ 48 long user data pointer
UDPBfrReturn returns a receive buffer to the UDP driver that had been passed to you because of a successful UDPRead call that returned a nonzero amount of data.
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
invalidBufPtr the user does not own the UDP receive buffer
UDPWrite
Parameter block Æ 26 word csCode = UDPWrite
Æ 28 long stream pointer
Æ 34 long remote IP address
Æ 38 word remote UDP port
Æ 40 long pointer to WDS
Æ 44 byte checksum flag
Æ 46 word reserved; must be set to zero
Æ 48 long user data pointer
UDPWrite sends a datagram on a UDP stream.
The datagram’s destination is specified by the remote IP address and remote UDP parameter ports. The buffers described by the WDS must not be modified or relocated until the command has been completed. The WDS can describe up to 6 buffers. The total length of the UDP data described by the WDS must be between 0 and 8,192 inclusive. If the Checksum flag is nonzero, UDP computes and transmits a checksum; otherwise, the checksum is transmitted as 0. The reserved field must be set to 0.
In an Ethernet environment, the size of UDPWrite packets should be restricted to less than or equal to 8192 bytes. Packets of this size can usually be reassembled by computers operating in Ethernet environments. In a LocalTalk environment, the size of UDPWrite packets should be restricted to less than or equal to 1458 bytes because of Datagram Delivery Protocol-Internet Protocol (DDP-IP) gateway performance considerations.
Note: Unless you have prior knowledge of the capabilities of the destination machine, the UDPWrite size should be limited to the value returned by the UDPMTU call for maximum interoperability.
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
invalidWDS too many buffers are in WDS or WDS pointer is NIL
invalidLength the total amount of data described by the WDS was greater than 65,535 bytes
insufficientResources too many datagrams are outstanding in the transmit queue
ipNoFragMemErr insufficient internal memory was available to fragment the packet
ipRouteErr unable to send the packet to an off-network destination because all gateways are down
UDPRelease
Parameter block Æ 26 word csCode = UDPRelease
Æ 28 long stream pointer
¨ 32 long pointer to receive buffer area
¨ 36 long length of receive buffer area
Æ 46 long user data pointer
UDPRelease closes a UDP stream. Any outstanding commands on that stream are terminated with an error. The ownership of the receive buffer area used to create the UDP stream passes back to you.
Before UDPRelease is called, you must make sure that all pending UDPWrite commands have been completed. There is no way to abort a UDPWrite command in progress.
Note: UDP Release must be called to release memory that is held by the driver. Failure to do so may produce unpredictable results.
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
UDPMTU
Parameter block Æ 26 word csCode = UDPMaxMTUSize
¨ 32 word maximum datagram size
Æ 34 long remote address
Æ 38 long user data pointer
UDPMTU returns the maximum size of UDP data that can be sent in a single datagram without fragmentation. This number does not include the IP and UDP headers. The value is relative to the destination address. If the address is on the local network, the network MTU size is returned; otherwise, a value of 548 is returned.
Result codes noErr no error
UDP Multiport Create
Parameter block Æ 26 word csCode = UDPMultiCreate
¨ 28 long stream pointer
Æ 32 long pointer to receive buffer area
Æ 36 long length of receive buffer area
Æ 40 long pointer to asynchronous notification routine (ASR)
Æ 44 word starting UDP port
Æ 46 long user data pointer
Æ 50 word ending port
UDP Multiport Create opens UDP connections on a consecutive series of ports. This routine is similar to UDPCreate except that it takes a starting and ending port instead of a single UDP port. The starting port must not be zero. The connection is established on a range of ports, from the starting port to the ending port, inclusive. The UDP Multiport Send routine must be used with this type of connection stream (see the next section, “UDP Multiport Send”). Reading datagrams from this type of stream is identical to UDPRead, except that the receiving port may change from datagram to datagram.
Result codes noErr no error
streamAlreadyOpen an open stream is already using this receive buffer area
invalidLength the receive buffer area is too small
invalidBufPtr the receive buffer area pointer is 0
duplicateSocket an open stream is already using this local UDP port
insufficientResources 64 UDP streams are already open
UDP Multiport Send
Parameter block Æ 26 word csCode = UDPMultiSend
Æ 28 long stream pointer
Æ 34 long remote IP address
Æ 38 word remote UDP port
Æ 40 long pointer to WDS
Æ 44 byte checksum flag
Æ 46 word reserved
Æ 48 long user data pointer
Æ 52 word local port
UDP Multiport Send sends a datagram from a specified port. (See “UDPWrite.”)
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
invalidWDS too many buffers are in WDS or WDS pointer is NIL
invalidLength the total amount of data described by the WDS was greater than 65,535 bytes
insufficientResources too many datagrams are outstanding in the transmit queue
ipNoFragMemErr insufficient internal memory is available to fragment the packet
ipRouteErr unable to send the packet to an off-network destination because all gateways are down
UDP Multiport Receive
Parameter block Æ 26 word csCode = UDPMultiRead
Æ 28 long stream pointer
Æ 32 word command timeout value in seconds
(0 = infinite)
¨ 34 long remote IP address
¨ 38 word remote UDP port
¨ 40 long pointer to UDP data
¨ 44 word length of UDP data
Æ 46 word reserved; must be set to 0
Æ 48 long user data pointer
¨ 52 long destination host
¨ 56 word destination port
UDP Multiport Receive receives data from a port created with the UDP Multiport Create command. The port and host address on which the packet was received is specified in the destination port and destination host parameter-block fields.
Result codes noErr no error
invalidStreamPtr the specified UDP stream is not open
commandTimeout no data arrived within the specified period
connectionTerminated a UDPRelease command closed the UDP stream
C parameter-block definitions
The following C type definitions are used with parameter-block Device Manager calls to UDP:
The following parameter block is used for UDPCreate, UDPMultiCreate, and UDPRelease calls:
typedef struct UDPCreatePB {
Ptr rcvBuff;
unsigned long rcvBuffLen;
UDPNotifyProc notifyProc;
unsigned short localPort;
Ptr userDataPtr;
udp_port endingPort;
} UDPCreatePB;
Continued on following page .
typedef struct UDPSendPB {
unsigned short reserved;
ip_addr remoteHost;
udp_port remotePort;
Ptr wdsPtr;
Boolean checkSum;
unsigned short sendLength;
Ptr userDataPtr;
udp_port localPort;
} UDPSendPB;
The following parameter block is used with the UDPRead, UDPMultiReceive, and UDPBfrReturn commands:
typedef struct UDPReceivePB {
unsigned short timeOut;
ip_addr remoteHost;
udp_port remotePort;
Ptr rcvBuff;
unsigned short rcvBuffLen;
unsigned short secondTimeStamp;
Ptr userDataPtr;
ip_addr destHost;
udp_port destPort;
} UDPReceivePB;
typedef struct UDPMTUPB {
unsigned short mtuSize;
ip_addr remoteHost;
Ptr userDataPtr;
} UDPMTUPB;
typedef struct UDPiopb {
char fill12[12];
UDPIOCompletionProc ioCompletion;
short ioResult;
char *ioNamePtr;
short ioVRefNum;
short ioCRefNum;
short csCode;
StreamPtr udpStream;
union {
struct UDPCreatePB create;
struct UDPSendPB send;
struct UDPReceivePB receive;
struct UDPMTUPB mtu;
} csParam;
} UDPiopb;
4 Transmission Control Protocol
The Transmission Control Protocol (TCP) is a highly reliable, connection-oriented byte-stream protocol. It is designed to operate over a wide variety of networks and to provide virtual circuit service with orderly transmission of user data. TCP serves as the basis for a reliable interprocess communication mechanism on top of the IP layer where loss, damage, duplication, delay, or misordering of packets can occur.
Data structures
This section describes TCP Read and Write Data Structures and the receive buffer area.
Read and Write Data Structures
The MacTCP driver uses Read Data Structures and Write Data Structures (RDS/WDS) to pass data between the user and TCP. These structures allow a single read or write operation to handle multiple blocks of data; that is, they allow scatter-read and gather-write capability. Figure 4-1 shows TCP Read and Write Data Structures.
Figure 4-1 TCP Read and Write Data Structures
The simplest possible Read and Write Data Structures are 8 bytes in length: a word length, a long pointer, and a terminating word of 0. Up to 65,000 buffers can be described by an RDS/WDS used to transfer data between TCP and the user.
Receive buffer area
TCP does not allocate memory for storing TCP stream databases or for buffering received datagrams. Instead, you are required to pass TCP enough memory for these purposes in the TCPCreate call. This has two advantages:
n The buffer memory can be allocated off the application heap instead of the system heap, which is very limited.
n You have control over the buffering provided by TCP and can allocate the appropriate amount of memory for the type of application and performance level desired.
The buffer area for incoming datagrams belongs to the MacTCP driver as long as the TCP stream is open. When TCPRelease is called, this memory is returned to you and you can then reuse it or return it to the system.
An application should allocate memory by first finding the MTU of the physical network (see the UDPMTU section in Chapter 3). Some network devices supported by MacTCP have very large MTU sizes. If an appropriate amount of memory is not allocated to the TCP connection, the connection will behave unpredictably. The minimum memory allocation should be 4N + 1024, where N is the size of the physical MTU returned by the UDPMTU call.
Using TCP
This section describes how to send and receive TCP segments.
Streams and connections
A TCP stream supports one connection at a time. But a TCP connection on a stream can be closed and another connection opened without releasing the TCP stream. The MacTCP driver can support 64 open TCP streams simultaneously.
Asynchronous notification routine
When a TCP stream is created, a routine can be registered that TCP uses to notify you of asynchronous events relevant to that TCP stream. This routine is called the asynchronous notification routine (ASR).
Examples of events that the MacTCP driver communicates to the user by means of an ASR include Timeout Expired, Data Arrived, and Connection Terminated. Since the ASR is called from the interrupt level, it cannot allocate or release memory. In addition, synchronous MacTCP driver commands cannot be issued from an ASR.
Connection opening
To listen for an incoming connection, use the TCPPassiveOpen command. This command can be used to specify whether any incoming connection will be accepted or only connections from a particular remote IP address and TCP port.
To initiate outgoing connections, use the TCPActiveOpen command.
Receiving data
Two methods are available for receiving data: a high-performance method and a simple method. You can choose the method that best suits the application or combine the two methods if desired.
Using the TCPNoCopyRcv routine is the high-performance method. Data is delivered to the user directly from the internal TCP receive buffers and no copy is required. An RDS is formatted to allow many received segments to be delivered to the user in one TCPNoCopyRcv command. TCPBfrReturn must be called for every TCPNoCopyRcv that returns a nonzero amount of data in order to return the internal receive buffers to the MacTCP driver.
Using the TCPRcv routine is the simple method of receiving data. Data is copied from the TCP internal receive buffers into the user’s buffer, which can be of arbitrary length and location. No RDS is used and no TCPBfrReturn call is required.
Sending data
To send data on a connection that is already established, use the TCPSend command.
Both commands use WDSs to implement a gather-write capability. This allows you to send several noncontiguous chunks of data in one operation.
Timeouts
TCP normally provides some timeout services to the upper-layer protocol (ULP). This timeout service is known as the ULP timeout. If there is data to send on a connection, but for some specified period of time the data cannot be sent (either because the remote TCP is not set to receive any data or the data has been sent but the remote TCP has not acknowledged it), then the ULP timeout expires.
When the ULP timeout expires, TCP executes the specified ULP timeout action. There are two possible actions: abort the connection or report the timer expiration by means of an ASR and restart the timer.
In addition to this normal TCP timer, the MacTCP driver provides command timeouts on commands that are not subject to the ULP timer. These commands are TCPPassiveOpen, TCPNoCopyRcv, and TCPRcv.
A TCPPassiveOpen command instructs TCP to wait for an incoming connection. The ULP timer is not started until the first connection initiation segment arrives. To prevent a TCPPassiveOpen command from waiting indefinitely for a connection initiation segment to arrive, a command timeout is provided. If no connection initiation segment is received within the specified timeout period, the TCPPassiveOpen command is completed with an error code.
Similarly, the TCPNoCopyRcv and TCPRcv commands are not protected by the ULP timer. In the absence of command timeouts, both commands could wait indefinitely for data to arrive. If a command timeout is specified on a TCPNoCopyRcv or TCPRcv command, the command is always completed within the specified time period. If no data has arrived at that point, the command is completed with an error. If some data has arrived, the command is completed successfully, returning the data that has arrived so far.
Pushed data
Usually, TCP is allowed to collect data sent by means of TCPSend commands and to send that data in segments, as convenient. By setting the Push flag in the TCPSend command, TCP can be instructed to send all unsent data at once.
Similarly, TCP is allowed to collect received data internally and deliver it with reasonable promptness to the user. However, when pushed data arrives, TCP immediately delivers all received data to the user.
Note that there is no necessary relationship between the Push flag in a TCPSend command and segment boundaries. The push function does not provide a method of marking message boundaries.
Urgent mode
The urgent mechanism for TCP allows the sending user to prompt the receiving user to accept urgent data. It also permits the receiving TCP to indicate to the receiving user when all currently known urgent data has been received.
TCP does not define what the user is required to do when in urgent mode, but the general practice is that the receiving user takes action to process the arriving data quickly.
A receiving user can be put in urgent mode in two ways: by means of an Urgent flag in a TCPNoCopyRcv or TCPRcv command, or by an urgent ASR notification. The user is always taken out of urgent mode by a Mark flag in the TCPNoCopyRcv or TCPRcv command that contains the last byte of urgent data.
To send data as urgent, you must set the Urgent flag in the TCPSend command.
Note: RFC 793 contained an incorrect specification pertaining to the description of the end of urgent data. Consequently, many hosts have implemented urgent data incorrectly. RFC 1122 corrects the definition of urgent data. The MacTCP driver is compliant with both specifications, allowing you to send urgent data using either specification.
Since there’s currently no known way to programmatically determine whether the remote site is compliant with RFC 793 or 1122, there’s no way to determine which urgent data format to use. You must devise your own strategy.
It is recommended that you make urgent data self-formatting to circumvent the problem of detecting the exact end of urgent data.
An application can send urgent data according to RFC 793 or 1122. Unless an application specifies otherwise, urgent data is sent using the method specified in RFC 1122.
Connection closing
TCP closes communications gracefully. All outstanding Send requests are transmitted and acknowledged before the connection is allowed to close. You can issue several TCPSend commands followed by a TCPClose command and expect that all the data will be sent successfully to the remote TCP.
A TCPClose command means “I have no more data to send,” but it does not mean “I will receive no more data” or “shut down this connection immediately.” A connection may remain open indefinitely as the remote TCP continues to send data after a TCPClose command has been completed. When the remote TCP also issues a close command—and only then—the connection is closed. A TCPRcv command should be issued after a TCPClose command has been completed to make sure that all the data is received.
If the desired effect is to break the connection without any assurance that all data in transit is delivered, use the TCPAbort command.
Network management information
TCP keeps two types of network management information: global TCP information and stream-specific information, which is relevant only to a particular stream.
The TCPGlobalInfo command makes global TCP information accessible. This command returns pointers to the actual structures where TCP stores this information. Thus, the user has read-write access to this information.
The TCPStatus command makes stream-specific information accessible. Most stream-specific information is copied into the TCPStatus I/O parameter block, giving the user read-only access. But a direct pointer to the traffic statistics allows the user read-write access to those counters (see the section “TCPGlobalInfo” later in this chapter).
Formatting MacTCP commands
In most cases, a 0 value for a parameter in an I/O parameter block means that TCP will use its default value. Thus, you must initialize I/O parameter blocks and then fill in the required parameters, plus optional parameters.
TCP routines
This section presents calls to the TCP driver. Table 4-1 lists each TCP routine and its function.
Table 4-1 TCP routines
Routine Function
TCPCreate Opens a TCP stream
TCPPassiveOpen Listens for an incoming connection
TCPActiveOpen Initiates an outgoing call to a remote TCP
TCPSend Sends specified data on a connection
TCPNoCopyRcv Retrieves data that has been received on a connection
TCPBfrReturn Returns a set of receive buffers to the TCP driver
TCPRcv Retrieves data that has been received on a connection
TCPClose Signals that the user has no more data to send on this connection
TCPAbort Terminates the connection without trying to send outstanding data or deliver received data
TCPStatus Extracts information from TCP regarding a particular connection
TCPRelease Closes a TCP stream
TCPGlobalInfo Allows the user access to global statistics and parameters that affect the operation of TCP
TCPCreate
Parameter block Æ 26 word csCode = TCPCreate
¨ 28 long stream pointer
Æ 32 long pointer to receive buffer area
Æ 36 long length of receive buffer area
Æ 40 long pointer to ASR
Æ 44 long user data pointer
TCPCreate opens a TCP stream. A TCP stream is not equivalent to a TCP connection. The MacTCP driver returns a pointer to a stream database. The stream pointer is an input parameter in all subsequent commands affecting the stream.
The receive buffer area is a block of memory that TCP uses to buffer incoming segments. Ownership of this block of memory passes to TCP. The memory—a minimum of 4096 bytes—cannot be modified or relocated until TCPRelease is called. The size of the receive window that TCP offers is based on the size of the receive buffer area passed to TCP in the TCPCreate call. High-performance and block-oriented applications should provide TCP with a large receive buffer area: 16 kilobytes (KB) is recommended and up to 128 KB can be useful in certain applications. Character-oriented applications can use the minimum value of 4096 bytes; however, at least 8192 bytes are recommended.
An ASR may be provided. The ASR is called by TCP to notify you of asynchronous events such as Data arrival, Urgent data outstanding, and Connection terminated. If the routine is 0, you are not notified of asynchronous events.
Result codes noErr no error
streamAlreadyOpen an open stream is already using this receive buffer area
invalidLength the receive buffer area is too small
invalidBufPtr the receive buffer area pointer is 0
insufficientResources 64 TCP streams are already open
TCP asynchronous notification routine
The TCP asynchronous notification routine (ASR) is a user-supplied routine called by TCP to notify you of asynchronous events relevant to a particular TCP stream. You register this routine with TCP in the TCPCreate call.
Since this routine is called at interrupt level, it cannot release or allocate memory. An ASR routine can issue additional asynchronous MacTCP driver calls.
The C description of the ASR is as follows:
pascal void TCPNotifyProc (
StreamPtr tcpStream,
unsigned short eventCode,
Ptr userDataPtr,
unsigned short terminReason,
struct ICMPReport *icmpMsg);
Register A1 contains a pointer to the Internet Control Message Protocol (ICMP) report structure if the event code in D0 is ICMP received, A2 contains the user data pointer, A5 is already set up to point to application globals, D0 (word) contains an event code, and D1 contains a reason for termination.
Event codes closing all data on this connection has been received
and delivered
ULP timeout no response from the remote TCP; reported only if TCP is configured to report a timeout instead of aborting the connection
terminate connection no longer exists
data arrival data arrived, no receive commands outstanding
urgent data outstanding user should go into urgent mode
ICMP message received an Internet Control Message has been received on the stream; register A1 points to the ICMP report
For the terminate event, a reason for connection termination is given in D1 (word):
remote abort the remote TCP aborted the connection
network failure currently not in use
security/precedence invalid security option or precedence level
mismatch
ULP timeout the ULP timeout expired; ULP timeout action is abort
ULP abort the user issued a TCPAbort command
ULP close the connection closed gracefully
service failure unexpected connection initiation segment read
Note: Refer to the Appendix for the values of these types.
A closing notification means that the remote TCP has sent all the data it intends to send on this connection and that all data has been delivered to the user. Closing notification does not mean that the connection has been broken. You can continue to send data for an arbitrary length of time after a closing notification is given. Only when you issue a TCPClose command will the connection be terminated.
The ULP timeout notification is given if the configured ULP timeout action for this connection is report, and the local TCP cannot get some data sent or acknowledged (or both), within the specified ULP timeout period. The ULP timer is restarted after notification and expires again in another ULP timeout period if nothing changes.
For each connection, TCP issues exactly one terminate notification when the connection is broken. This rule applies both when the connection closes gracefully and when the connection terminates in error.
Data arrival notification is given if a segment arrives and no receive commands are outstanding. Even if more data arrives later, TCP does not issue another data arrival notification until a receive command has been issued and completed. In other words, a data arrival notification is not given with every segment that arrives, but instead is intended to prompt you to issue a receive command.
Urgent notification is given only if no receive commands are pending when TCP discovers outstanding urgent information on the connection. If there are outstanding receive commands, they are completed with the Urgent flag set, starting the reception of data in urgent mode.
An ICMP message reports an error in the processing of a datagram that was sent on a TCP stream. When an ICMP message is received, a data structure is passed up by TCP to the client to describe the received message. This data structure, called an ICMP report, has the following format:
0 word stream pointer
2 long local IP address of stream
6 word local TCP port of stream
8 long remote IP address (destination of original datagram)
12 word remote TCP port
14 word ICMP message type
16 word optional additional information
18 long optional additional information pointer
The values for the ICMP message type are as follows:
0 net unreachable
1 host unreachable
2 protocol unreachable
3 port unreachable
4 fragmentation required
5 source route failed
6 time exceeded
7 parameter problem
8 missing required option
Codes 0–3 are defined as follows:
n Net unreachable indicates that, according to the information in a gateway routing table, the network specified in the IP destination field of a TCP segment is unreachable.
n Host unreachable indicates that a gateway determined that the host specified in the IP destination field of a TCP segment is unreachable.
n Protocol unreachable indicates that a TCP segment was delivered to the destination host, but there was no process on that host to receive TCP segments.
n Port unreachable indicates that a TCP segment was delivered to the destination host, but there was no client of TCP listening on that particular TCP port.
If the TCP stream is configured for the ULP abort timeout action, the TCP client need not take any action in response to destination unreachable messages (they are informational only).
TCP breaks the connection if there is data to send, but it is not acknowledged within the ULP timeout period. If, however, this TCP stream has been configured for the ULP report timeout action, then the TCP user has taken responsibility for deciding when and if the remote host is no longer available, and the connection should be broken.
A single destination unreachable message should not be taken too seriously because such messages may be received occasionally when the topology of the internet changes. But if several successive TCPSend commands each result in an ICMP report indicating destination unreachable, the TCP client should assume that the remote host has either crashed or is no longer accessible and should break the connection.
Codes 4–8 are defined as follows:
n Fragmentation required indicates that the TCP user has set the Don’t Fragment flag in a TCPOpen command, yet a segment on that TCP connection could not be delivered to its destination without fragmentation. To avoid this, don’t set the Don’t Fragment flag on TCPOpen commands.
n Source route failed indicates that the TCP user has specified the route this datagram should take in the IP options but that particular route was not available.
n Time exceeded indicates that the Time to Live specified in a TCPOpen command was too short to allow a TCP segment on this TCP stream to be delivered through all the necessary gateways on the way to its destination. A longer Time to Live value should be specified in the TCPOpen command.
n Parameter problem indicates that the IP header used on a TCP segment was not acceptable by either an intermediate gateway or the final destination. The additional information pointer in the ICMP report structure points to a static copy of the IP header used for sending segments on this TCP connection. The additional information value indicates a byte offset in the IP header where the parameter problem exists. For example, an offset of 1 indicates that the Type of Service field is invalid, and an offset of 20 indicates that the first option present is invalid.
n Missing required option means that the remote TCP requires that a specific IP option be present in the IP header. The IP option type code that is required by the remote TCP is passed in the additional information field.
Much of the information that asynchronous notifications pass to you is also available in other ways. For example, you can tell that the remote TCP has closed a connection either by waiting for a closing notification or by submitting TCPRcv commands until one is returned with a connectionClosing error.
TCPPassiveOpen
Parameter block Æ 26 word csCode = TCPPassiveOpen
Æ 28 long stream pointer
Æ 32 byte ULP timeout value in seconds; 0 = use default
Æ 33 byte ULP timeout action; 0 = report,
nonzero = abort
Æ 34 byte validity bits for optional parameters
Æ 35 byte command timeout in seconds; 0 = infinity
´ 36 long remote IP address; can be 0
´ 40 word remote TCP port; can be 0
¨ 42 long local IP address
´ 46 word local TCP port; if 0, TCP assigns an unused port
Æ 48 byte type of service
Æ 49 byte precedence
Æ 50 byte don’t fragment flag
Æ 51 byte time to live
Æ 52 byte security flag
Æ 53 byte IP option count
Æ 54 var. IP options
Æ 94 long user data pointer
TCPPassiveOpen listens for an incoming connection. The command is completed when a connection is established or when an error occurs.
Several fields in the TCPPassiveOpen command are optional. To indicate whether the user is including these optional parameters, a set of validity bits is defined as follows:
bit 4 precedence parameter is valid
bit 5 type of service parameter is valid
bit 6 ULP timeout action parameter is valid
bit 7 ULP timeout value parameter is valid
For example, a value of 0xC0 would mean that the ULP timeout value and action parameters are valid. If a validity bit is 0, TCP uses its default value for that parameter.
If the remote IP address and remote TCP port are 0, a connection is accepted from any remote TCP. If they are nonzero, a connection is accepted only from that particular remote TCP. If the local TCP port is 0, TCP assigns an unused port value.
If a connection is partly established but cannot be completed within the ULP timeout period after the first connection opening segment arrives, the ULP action is taken. If the ULP timeout action is abort (the default value), the connection is broken and the TCPPassiveOpen command is completed in error. If the ULP timeout action is report, an ASR call informs the ULP, and the ULP timer is restarted. The minimum value of the ULP timeout is 2 seconds; 0 means that TCP should use its default value of 2 minutes.
If no connection opening packet arrives within the specified command timeout period after the TCPPassiveOpen command is issued, the command is completed in error. The minimum value of the command timeout is 2 seconds; 0 means infinite.
You have control over many fields in the IP header of all segments sent on this connection. You can set these fields only when the connection is opened. They stay fixed during the connection.
The type of service is a 3-bit field:
bit 0 set for low delay
bit 1 set for high throughput
bit 2 set for high reliability
For example, a value of 0x02 means high throughput. The default value is 0.
Precedence has the following values:
0 routine
1 priority
2 immediate
3 flash
4 flash-override
5 CRITIC/ECP
6 internetwork control
7 network control
The default value for precedence is 0.
If the Don’t Fragment flag is nonzero, all segments sent on this connection are prohibited from being fragmented by the local IP or any intermediate IP. If a segment cannot be delivered without fragmentation, it’s discarded.
The Time to Live indicates the maximum time that segments on this connection are allowed to remain in the internet system. This value is decreased by every IP module that processes the segment; thus, it is effectively a maximum hop count (the number of times a segment can pass through a module). The minimum value is 2; 0 means TCP should use its default value (the default value is 60).
If the Security flag is nonzero, TCP inserts its configured default IP security option into all segments sent on this connection. In addition, for all arriving segments that contain a security option, TCP verifies that the security matches the configured default security. Note that this flag is relevant only if no security option is present in the user-specified IP options.
Finally, you can specify additional IP options to be sent with every segment. The option count is the number of long words in the IP option field. Pad bytes of 0 should be appended to the IP options so that the options are an integral number of long words. The maximum value of the option count field is 10 unless the Security flag is also nonzero, in which case the maximum value is 9.
TCP does not perform any verification on the user-specified IP options, but simply inserts them into the IP header of every segment sent on the connection. If you specify an invalid list of IP options, the result cannot be predicted. See Request for Comment (RFC) 894 for the proper format of IP options.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionExists this TCP stream already has an open connection
duplicateSocket a connection already exists between this local IP address and TCP port, and the specified remote IP address and TCP port
commandTimeout no connection attempt was received in the specified time-out period
openFailed the connection came halfway up and then failed
TCPActiveOpen
Parameter block Æ 26 word csCode = TCPActiveOpen
Æ 28 long stream pointer
Æ 32 byte ULP timeout value in seconds; 0 = use default
Æ 33 byte ULP timeout action; 0 = report,
nonzero = abort
Æ 34 byte validity bits
Æ 36 long remote IP address; cannot be 0
Æ 40 word remote TCP port; cannot be 0
¨ 42 long local IP address
´ 46 word local TCP port; if 0, TCP assigns an unused port
Æ 48 byte type of service
Æ 49 byte precedence
Æ 50 byte don’t fragment flag
Æ 51 byte time to live
Æ 52 byte security flag
Æ 53 byte IP option count
Æ 54 byte[40] IP options
Æ 94 long user data pointer
TCPActiveOpen initiates an outgoing call to a remote TCP. The command is completed when a connection is established or when an error occurs.
TCPActiveOpen accepts the same parameters as TCPPassiveOpen, except that the remote IP address and remote TCP port must be specified. Further, no command timeout is provided; if the connection cannot be established within the ULP timeout period, the command is completed in error.
See TCPPassiveOpen for a description of other parameters.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionExists this TCP stream already has an open connection
duplicateSocket a connection already exists between this local IP address and TCP port, and the specified remote IP address and TCP port
openFailed the connection came halfway up and then failed
TCPSend
Parameter block Æ 26 word csCode = TCPSend
Æ 28 long stream pointer
Æ 32 byte ULP timeout value in seconds
Æ 33 byte ULP timeout action; nonzero = abort,
0 = report
Æ 34 byte validity bits
Æ 35 byte push flag
Æ 36 byte urgent flag
Æ 38 long WDS pointer
Æ 42 long reserved
Æ 46 word reserved
Æ 48 long user data pointer
TCPSend sends the specified data over the connection. The command is completed when all data has been sent and acknowledged or when an error occurs.
If all data cannot be sent and acknowledged within the ULP timeout period, then the ULP action is taken. If the ULP action is abort, the connection is broken, all pending commands are returned, and a terminate notification is given. If the ULP action is report, a ULP timeout notification is given.
Several fields in the TCPPassiveOpen command are optional. To indicate whether the user is including these optional parameters, a set of validity bits is defined as follows:
bit 6 ULP timeout action parameter is valid
bit 7 ULP timeout value parameter is valid
If the Push flag is nonzero, TCP sends the data immediately without waiting to see if more TCPSend commands are issued. If the Urgent flag is 2, TCP sends the data using the noncompliant method described by RFC 793. If the Urgent flag is any other nonzero value, TCP sends the data using the method described by RFC 1122. For more information about the TCP urgent mechanism, refer to the section “Urgent Mode” earlier in this chapter.
The WDS can be arbitrarily complex; that is, there is no limit to the number of buffers that can be sent in a TCPSend command. However, the total number of data bytes described by the WDS must be between 1 and 65,535, inclusive. You must not modify or relocate the WDS and the buffers it describes until the TCPSend command has been completed.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
invalidLength the total amount of data described by the WDS was either 0 or greater than 65,535 bytes
invalidWDS the WDS pointer was 0
connectionDoesntExist there is no open connection on this TCP stream
connectionClosing a TCPClose command was already issued, so there is no more data to send on this connection
connectionTerminated the connection was broken; the reason will be given in a terminate ASR
TCPNoCopyRcv
Parameter block Æ 26 word csCode = TCPNoCopyRcv
Æ 28 long stream pointer
Æ 32 byte command timeout in seconds
¨ 34 byte mark flag
¨ 35 byte urgent flag
Æ 42 long RDS pointer; RDS is modified by TCP
Æ 46 word number of entries in RDS excluding terminating 0; not modified by TCP
Æ 48 word reserved
Æ 50 long user data pointer
TCPNoCopyRcv retrieves data that has been received on a connection. Data is not copied out of the internal buffers of TCP; rather, an RDS is formatted to allow the user access to the TCP data in place. This command offers significant performance improvements over TCPRcv commands.
The command is completed when
n pushed data arrives
n urgent data is outstanding
n a reasonable period passes after the arrival of nonpush, nonurgent data
n the RDS is full; that is, the received data is in more noncontiguous chunks than the RDS can describe
n the amount of data received is greater than or equal to 25 percent of the total receive buffering for this stream
n the command timeout expires
You must allocate memory for the RDS, which can contain an unlimited number of elements. The specified number of entries in the RDS does not include the terminating 0. For example, the simplest possible RDS has one element and is 8 bytes in length: a word length field, a long pointer field, and a terminating word length field of 0.
TCP formats the RDS to point to the received TCP data. The RDS may not be completely filled by TCP. For example, if you pass an RDS three entries, TCP may complete the TCPNoCopyRcv command with the RDS describing only one buffer. TCP does not modify the field in the TCPNoCopyRcv command that indicates the number of entries in the RDS; rather, it places a terminating zero in the RDS itself.
The command timeout period starts when the receive command is issued, not when the first byte of data arrives. If no data arrives within this timeout period, the TCPNoCopyRcv command is completed in error. If some data has arrived when the command timeout expires, the TCPNoCopyRcv command is completed successfully, returning the data that has arrived so far. A command timeout of 0 indicates an infinite timeout period. In this case, the TCPNoCopyRcv command is not completed until some data has arrived.
If the Urgent flag is nonzero, the data returned by this command is the beginning of the outstanding urgent data. This flag is one of two mechanisms that puts you in urgent mode. The other mechanism is by means of an urgent ASR notification, which is used when there are no outstanding TCPNoCopyRcv or TCPRcv commands.
If the Mark flag is nonzero, the data returned by this command ends the urgent data. Since TCP does not deliver urgent and nonurgent data together, the last byte of data described by the RDS is the last byte of urgent data. The Mark flag is the only mechanism for taking you out of urgent mode.
The Urgent flag is set only on the first TCPNoCopy Rcv or TCPRcv command that contains urgent data. The Mark flag will be set only on the last TCPNoCopyRcv or TCPRcv command that contains urgent data. For example, if three TCPNoCopyRcv or TCPRcv commands are required to deliver all urgent data, the settings of the Urgent and Mark flags will be as follows:
Urgent flag Mark flag
First TCPNoCopyRcv/TCPRcv command 1 0
Second TCPNoCopyRcv/TCPRcv command 0 0
Third TCPNoCopyRcv/TCPRcv command 0 1
Both the Urgent flag and the Mark flag can be set in a single TCPNoCopyRcv or TCPRcv command if all outstanding urgent data can be delivered in a single command.
You are responsible for calling TCPBfrReturn after every TCPNoCopyRcv command that is completed successfully, in order to return the receive buffers owned by the TCP driver. The RDS must be returned unmodified so that the TCP driver can correctly recover the appropriate receive buffers.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionDoesntExist this TCP stream has no open connection
invalidLength the RDS has 0 entries
invalidBufPtr the RDS pointer was 0
commandTimeout no data arrived within the specified timeout period
connectionClosing all data on this connection has already been delivered
connectionTerminated the connection was broken; the reason will be given in a terminate ASR
TCPBfrReturn
Parameter block Æ 26 word csCode = TCPRcvBfrReturn
Æ 28 long stream pointer
Æ 42 long RDS pointer
Æ 50 long user data pointer
TCPBfrReturn returns to the TCP driver a set of receive buffers that a successfully completed TCPNoCopyRcv command passed directly to the user. The RDS must be identical to the RDS given to the user when the TCPNoCopyRcv command is completed. TCPBfrReturn returns an error if you attempt to return a set of buffers more than once.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionDoesntExist this TCP stream has no open connection
invalidBufPtr the RDS pointer was 0
invalidRDS the RDS refers to receive buffers not owned by the user
TCPRcv
Parameter block Æ 26 word csCode = TCPRcv
Æ 28 long stream pointer
Æ 32 byte command timeout in seconds
¨ 34 byte mark flag
¨ 35 byte urgent flag
Æ 36 long receive buffer pointer
´ 40 word receive buffer length
Æ 48 word reserved
Æ 50 long user data pointer
TCPRcv retrieves data that has been received on a connection. Data is copied out of the TCP internal buffers into the user’s buffer. The command is completed when
n enough data has arrived to fill the receive buffer
n pushed data arrives
n urgent data is outstanding
n a reasonable period passes after the arrival of nonpushed, nonurgent data
n the amount of data received is greater than or equal to 25 percent of the total receive buffering for this stream
n the command timeout expires
The command timeout period starts when the receive command is issued, not when the first byte of data arrives. If no data arrives within this command timeout period, the TCPRcv command is completed in error. If some data has arrived when the command timeout expires, the TCPRcv command is completed successfully. A command timeout of 0 means infinite; the TCPRcv command will not be completed until some data has arrived.
If the Urgent flag is nonzero, the data returned by this command is the beginning of the outstanding urgent data. This flag is one of two mechanisms that puts you in urgent mode. The other mechanism is by means of an urgent ASR notification, which is used when there are no outstanding TCPNoCopyRcv or TCPRcv commands.
If the Mark flag is nonzero, the data returned by this command ends the urgent data. Since TCP does not deliver urgent and nonurgent data together, the last byte of data in the receive buffer is the last byte of urgent data. The Mark flag is the only mechanism for taking you out of urgent mode.
The Urgent flag is set only on the first TCPNoCopyRcv or TCPRcv command that contains urgent data. The Mark flag is set only on the last TCPNoCopyRcv or TCPRcv command that contains urgent data. For example, if three TCPNoCopyRcv or TCPRcv commands are required to deliver all urgent data, the settings of the Urgent and Mark flags will be as follows:
Urgent flag Mark flag
First TCPNoCopyRcv/TCPRcv command 1 0
Second TCPNoCopyRcv/TCPRcv command 0 0
Third TCPNoCopyRcv/TCPRcv command 0 1
Both the Urgent flag and the Mark flag can be set in a single TCPNoCopyRcv or TCPRcv command if all outstanding urgent data can be delivered in a single command.
The amount of data actually received is found in the receive buffer length field.
If the TCPRcv command is completed in error, the receive buffer length is not modified by TCP, but no data is returned.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
invalidLength the receive buffer length was 0
invalidBufPtr the receive buffer pointer was 0
commandTimeout no data arrived within the specified timeout period
connectionDoesntExist this TCP stream has no open connection
connectionClosing all data on this connection has already been delivered
connectionTerminated the connection was broken; the reason will be given in a terminate ASR
TCPClose
Parameter block Æ 26 word csCode = TCPClose
Æ 28 long stream pointer
Æ 32 byte ULP timeout value in seconds
Æ 33 byte ULP timeout action; 0 = report,
nonzero = abort
Æ 34 byte validity bits
Æ 35 long user data pointer
TCPClose signals that the user has no more data to send on the connection. It does not mean that the connection should be broken. The remote TCP must also issue a close before the connection can be gracefully closed, so a connection may remain an arbitrary amount of time after you have issued a TCPClose. To break a connection without ensuring that all data has been sent and acknowledged, use the TCPAbort command. (See the section “Connection Closing” earlier in this chapter.)
The command is completed when the FIN flag has been sent and acknowledged. If the FIN is not acknowledged within the ULP timeout period, the ULP timeout action is taken. If the ULP action is abort, the connection is broken, all pending commands are returned, and a terminate notification is given. If the ULP action is report, a ULP timeout notification is given.
Several fields in the TCPPassiveOpen command are optional. To indicate whether the user is including these optional parameters, a set of validity bits is defined as follows:
bit 6 ULP timeout action parameter is valid
bit 7 ULP timeout value parameter is valid
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionDoesntExist this TCP stream has no open connection
connectionClosing one TCPClose command was already issued for this connection
connectionTerminated the connection was broken; the reason will be given in a terminate ASR
TCPAbort
Parameter block Æ 26 word csCode = TCPAbort
Æ 28 long stream pointer
Æ 32 long user data pointer
TCPAbort terminates the connection without attempting to send all outstanding data or to deliver all received data. TCPAbort returns the TCP stream to its initial state. You are also given a terminate notification.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionDoesntExist this TCP stream has no open connection
TCPStatus
Parameter block Æ 26 word csCode = TCPStatus
Æ 28 long stream pointer
¨ 32 byte ULP timeout value in seconds
¨ 33 byte ULP timeout action; 0 = report,
nonzero = abort
¨ 38 long remote IP address
¨ 42 word remote TCP port
¨ 44 long local IP address
¨ 48 word local TCP port
¨ 50 byte type of service
¨ 51 byte precedence
¨ 52 byte TCP connection state
¨ 54 word send window
¨ 56 word receive window
¨ 58 word amount of unacknowledged data
¨ 60 word amount of unread data
¨ 62 long security option pointer
¨ 66 long send unacknowledged
¨ 70 long send next
¨ 74 long congestion window
¨ 78 long receive next
¨ 82 long smoothed round-trip time in milliseconds
¨ 86 long last round-trip time in milliseconds
¨ 90 long maximum segment size that can be sent
¨ 94 long pointer to statistics block
Æ 98 long user data pointer
TCPStatus allows you to extract information from TCP regarding a particular connection.
See the TCPPassiveOpen command for a description of the usual open parameters (bytes 32–51).
The TCP connection state has the following values:
0 Closed no connection exists on this stream
2 Listen listening for an incoming connection
4 SYN received incoming connection is being established
6 SYN sent outgoing connection is being established
8 Established connection is up
10 FIN Wait 1 connection is up; close has been issued
12 FIN Wait 2 connection is up; close has been completed
14 Close Wait connection is up; close has been received
16 Closing connection is up; close has been issued and received
18 Last Ack connection is up; close has been issued and received
20 Time Wait connection is being broken
The send window is the amount of data the remote TCP is currently willing to accept from the local TCP. The receive window is the amount of data the local TCP is currently willing to accept from the remote TCP.
The statistics block has the following structure:
0 long number of data segments received
4 long number of data segments sent
8 long number of data segments retransmitted
12 long number of data bytes received
16 long number of duplicate data bytes received
20 long number of data bytes received beyond receive window
24 long number of data bytes sent
28 long number of data bytes retransmitted
32 struct size histogram of sent segments
The histogram is a variable-length structure of the following format:
0 word number of size buckets
2 word value: smallest segment size
4 long counter number: number of segments sent between this size and the next larger size
8 word value: second smallest segment size
10 long counter number: number of segments sent between this size and the next larger size
You are free to update the statistics block. Only the counters in the segment-size histogram should be modified. The number of size buckets and the segment-size value for each bucket cannot be changed.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
connectionDoesntExist this TCP stream has no open connection
TCPRelease
Parameter block Æ 26 word csCode = TCPRelease
Æ 28 long stream pointer
¨ 32 long pointer to receive buffer area
¨ 36 long length of receive buffer area
Æ 44 long user data pointer
TCPRelease closes a TCP stream. If there is an open connection on the stream, the connection is first broken as though a TCPAbort command had been issued.
The receive buffer area passed to the MacTCP driver in the TCPCreate call is returned to the user. You are now free to reuse or release this buffer area.
Result codes noErr no error
invalidStreamPtr the specified TCP stream is not open
TCPGlobalInfo
Parameter block Æ 26 word csCode = TCPGlobalInfo
¨ 32 long pointer to TCP parameters
¨ 36 long pointer to TCP statistics
¨ 40 long pointer to CDB table
Æ 44 long user data pointer
The TCPGlobalInfo command allows you access to
n parameters that affect the operation of TCP
n global statistics collected by TCP
You should not modify the TCP parameters. The structure has the following format:
0 long pointer to Pascal string describing retransmission timeout algorithm
4 long minimum value of retransmission timeout (in milliseconds)
8 long maximum value of retransmission timeout (in milliseconds)
12 long maximum segment size this TCP can receive
16 long maximum number of streams the MacTCP driver can support
20 long maximum value of receive window the MacTCP driver can offer
The TCP statistics are the sum of traffic information for all streams that have been opened since system startup time. The counters will wrap around to 0 when incremented past their maximum value. You can modify these statistics.
The TCP statistics structure has the following format:
0 long number of outgoing connections attempted
4 long number of outgoing connections opened
8 long number of incoming connections accepted
12 long number of connections that closed gracefully
16 long number of connections that were aborted
20 long number of data bytes received
24 long number of data bytes sent
28 long number of duplicate data bytes received
32 long number of data bytes retransmitted
36 long total number of segments received (includes acknowledgments)
40 long total number of segments sent (includes acknowledgments)
44 long number of segments received that contained all duplicate data
48 long number of segments retransmitted
Result codes noErr no error
C parameter-block definitions
The following C type definitions are used with parameter-block Device Manager calls to TCP:
Textual names are resolved to IP addresses using internal caches and the domain name server. The AddressXlation interface accomplishes this task by searching an internal table originally derived from the static file Hosts, making queries to domain name servers, and finding information in the internal cache of domain name server responses.
The AddressXlation.h header file
The AddressXlation.h interface supports the domain name resolver (DNR) function using the procedure calls listed in Table 5-1 and described in the following sections.
Table 5-1 AddressXlation.h routines
Routine Function
OpenResolver Opens the resolver and allocates internal resources
StrToAddr Converts an ASCII text string to the corresponding IP address
AddrToStr Converts an IP address into its text dotted decimal notation (W.X.Y.Z)
EnumCache Enumerates all the name-to-address mappings cached by the resolver
AddrToName Converts an IP address to its corresponding textual name using the resolver
HInfo Returns details about the system whose name is being queried
MXInfo Returns mail box information for the system whose name is being queried
CloseResolver Closes the resolver and deallocates internal resources
The OpenResolver call
extern OSErr OpenResolver(char *fileName);
The OpenResolver call must be made before any resolver queries are attempted. The full pathname of the default Hosts file must be passed in the fileName field. If the value NIL is passed, the resolver uses the filename Hosts in the default startup folder, which is typically the System Folder. The Hosts file is used to load the internal cache with name-to-address mappings and domain name server values. The syntax of this file is outlined on page 33 of Request for Comments (RFC) 1035.
Result codes Resource Manager error result codes may be returned.
The StrToAddr call
#define NUM_ALT_ADDRS 4
typedef struct hostInfo {
int rtnCode;
char cname[255];
unsigned long addr[NUM_ALT_ADDRS];
};
typedef pascal void (*ResultProcPtr)(
struct hostInfo *hostInfoPtr,
char *userDataPtr);
extern OSErr StrToAddr(
char *hostName,
struct hostInfo *hostInfoPtr,
ResultProcPtr ResultProc,
char *userDataPtr);
The hostInfo record is passed into the address translation routine in the StrToAddr call. The rtnCode indicates whether the result fields are valid for this call; a value of noErr indicates that the call was successful. The cname is the official name of the hostName that was specified. The addr array is a list of addresses for the hostName that was specified. Multiple addresses are returned for hosts that are multihomed.
StrToAddr takes a string in one of two forms and translates it into a 32-bit IP address. The string can be in IP dot notation (that is, W.X.Y.Z) or in a valid domain name syntax. The translated address is returned immediately if the passed in host is in IP dot notation or if the matching address is contained in the local cache. If the address is not contained in the local cache, the rtnCode is cacheFault and the domain name server is contacted to resolve the address. When the response has been returned from the domain name server or the domain name query has not been successfully completed, the ResultProc is called with the appropriate rtnCode and return information. The StrToAddr procedure can be called with a userDataPtr, which is user-defined and not modified by the resolver. The userDataPtr is returned when the ResultProc is called. Domain names that contain no domain name delimiters, that is, no dots (.), are terminated with the domain name suffix specified for the default domain name server in the Control Panel. They are terminated with a dot if no default is specified.
Result codes nameSyntaxErr the hostName field had a syntax error
cacheFault the name specified cannot be found in the cache
noResultProc no result procedure is passed to the address translation call when the resolver must be used to find the address
noNameServer no name server can be found for the specified name string
authNameErr this domain name does not exist
noAnsErr none of the known name servers are responding
dnrErr the domain name server has returned an error
outOfMemory not enough memory is available to issue the needed domain name resolver (DNR) query or to build the DNR cache
notOpenErr the driver isn’t open
The AddrToStr call
extern OSErr AddrToStr(unsigned long addr, char *addrStr);
The AddrToStr call takes an IP address and returns a string with the ASCII equivalent of the form W.X.Y.Z where W, X, Y, and Z are decimal numbers. The application must provide the storage for the return string. The string can have a maximum length of 16 bytes.
Result codes notOpenErr the driver isn’t open
The EnumCache call
typedef enum AddrClasses {
A = 1,
NS,
CNAME = 5,
HINFO = 13,
MX = 15,
lastClass = 32767
}AddrClasses;
typedef struct cacheEntryRecord {
char *cname;
unsigned short type;
unsigned short cacheClass;
unsigned long ttl;
union {
char *name;
ip_addr *addr;
} rdata;
};
typedef pascal void (*EnumResultProcPtr)(
struct cacheEntryRecord *cacheEntryRecordPtr,
char *userDataPtr);
extern OSErr EnumCache(
EnumResultProcPtr enumResultProc,
char *userDataPtr);
If the application wants to enumerate all the entries in the cache, the EnumCache procedure should be called. This procedure returns no errors and has completed enumerating the cache when it returns. For every entry in the cache, enumResultProc is called with a pointer to a cache entry. The fields and values returned in the CacheEntryRecord are as follows:
name The name of the entry.
type The type of the entry, where
—A (value = 1) is an address. The value of rdata is an addr.
—NS (value = 2) is a name server. The value of rdata is a name.
—CNAME (value = 5) is an alias for the canonical name (cname) found in the rdata field.
cacheClass The class of the entry. The only class allowed is IN (value 1).
ttl The time that the entry has to live in the cache relative to the current time (GetCurrent).
rdata The rdata field as determined by the type of entry specified in the type field.
Result codes notOpenErr the driver isn’t open
The AddrToName call
extern OSErr AddrToName(
ip_addr addr,
struct hostInfo *hostInfoPtr,
ResultProcPtr ResultProc,
char *userDataPtr);
The AddrToName call is used to acquire the canonical name of a host given its IP address. The domain name server is queried using an IN-ADDR query. The application passes to the AddrToName call the IP address of the host in question, a pointer to a hostInfo record, the result procedure to be notified with the result, and an optional user data pointer. The AddrToName call always returns immediately with the return code cacheFault or the return code noNameServer if no name server can be found in the internal name server lists that can resolve the DNR query. The passed-in result procedure is called with the appropriate result code. If the result code is noErr, the cname field contains the canonical name for the IP address passed to the AddrToName call.
Result codes cacheFault the name specified cannot be found in the
cache
noNameServer no name server can be found for the specified name string
authNameErr this domain name does not exist
noAnsErr none of the known name servers are responding
dnrErr the domain name server has returned an error
outOfMemory not enough memory is available to issue the needed DNR query or to build the DNR cache
notOpenErr the driver isn’t open
The HInfo call
typedef struct HinfoRec {
char cpuType[30];
char osType[30];
};
typedef struct returnRec {
int rtnCode;
char cname[255];
union {
unsigned long addr[NUM_ALT_ADDRS];
struct HInfoRec hinfo;
struct MXRec mx;
} rdata;
};
typedef pascal void (*ResultProc2Ptr)(
struct returnRec *returnRecPtr,
char *userDataPtr);
extern OSErr HInfo(
char *hostName,
struct returnRec *returnRecPtr,
ResultProc2Ptr resultProc,
char *userDataPtr);
The HInfo call returns details about the system whose name is being queried. The call returns two strings, cpuType and osType, that specify in ASCII the values of the CPU and operating system type.
The HInfo call follows the calling conventions for queries described in the section “DNR Operation” later in this chapter.
Result codes nameSyntaxErr the hostName field has a syntax error
noNameServer no name server can be found for the specified name string
noAnsErr none of the known name servers are responding
dnrErr the domain name server has returned an error
outOfMemory not enough memory is available to issue the needed DNR query or to build the DNR cache
notOpenErr the driver isn’t open
The MXInfo call
typedef struct MXRec {
unsigned short preference;
char exchange[255];
};
typedef struct returnRec {
int rtnCode;
char cname[255];
union {
unsigned long addr[NUM_ALT_ADDRS];
struct HInfoRec hinfo;
struct MXRec mx;
} rdata;
};
typedef pascal void (*ResultProc2Ptr)(
struct returnRec *returnRecPtr,
char *userDataPtr);
extern OSerr MXInfo
(char *hostName,
struct returnRec *returnRecPtr,
ResultProc2Ptr resultProc,
char *userDataPtr);
The MXInfo call returns mail box information for the system whose name is being queried. The call returns two values:
n preference, an unsigned integer specifying the preference that is given to the returned system name
n exchange, the domain name for the system that is receiving mail for the specified host
The MXInfo call follows the calling conventions for queries described in the section “DNR Operation” later in this chapter.
Result codes nameSyntaxErr the hostName field has a syntax error
noNameServer no name server can be found for the specified name string
noAnsErr none of the known name servers are responding
dnrErr the domain name server has returned an error
outOfMemory not enough memory is available to issue the needed domain name resolver (DNR) query or to build the DNR cache
notOpenErr the driver isn’t open
The CloseResolver call
extern OSerr CloseResolver ();
Before the application exits, the CloseResolver call must be made to release memory structures and terminate all outstanding domain name server calls. CloseResolver must not be called until all outstanding resolver calls have been completed.
Result codes notOpenErr the driver isn’t open
Binding the DNR to the application
The domain name resolver (DNR) in the MacTCP driver is implemented as a code resource in the MacTCP driver file.
A file called DNR.c in the Libraries Folder of the MacTCP release disk provides a working example of how to open the DNR. Compile and link this file to your application. MPW version 3.2 produces a file called DNR.o in the Libraries Folder of the MacTCP release disk that provides procedural access to the DNR. Sources have also been provided if you need to port the functionality to another development system.
To use the DNR, the application must first find the procedure pointers that are part of the DNR resource. In Macintosh system software version 6.0.x, the DNR resource, named dnrp, is attached to the driver file, which is in the System Folder of the startup disk. The driver file is of type cdev, creator ztcp. In Macintosh system software version 7.0, the driver file is in the Control Panels folder (see the chapter “The Finder Interface” in Inside Macintosh, Volume VI). The resource can be opened using the Resource Manager routines in the Toolbox.
Once the resource is opened, the first long word of the resource is a pointer to a procedure that jumps to the correct DNR procedure. You should make calls to this procedure using the procedure index value as the first argument of the call, followed by the arguments for the procedure as they are specified in the AddressXlation.h interface. The procedure assignments are as follows:
OpenResolver 1
CloseResolver 2
StrToAddr 3
AddrToStr 4
EnumCache 5
AddrToName 6
HInfo 7
MXInfo 8
DNR operation
This section describes how the domain name server (DNS) list is used when making DNS queries.
If a default name extension and server are identified in the Control Panel, they are used for all nonqualified requests. For example, if the name homer is passed to the DNR and the default extension is pundit.edu, the name homer.pundit.edu is used in the query; however, if the name homer.drama.pundit.edu is passed to the DNR, the extension is not appended.
The extension of the name passed to the DNR determines which name servers are chosen. Servers that match the full extension are found first, followed by servers that serve the ancestor of the full extension (for example, for the name homer.drama.pundit.edu, the server that serves drama.pundit.edu would be found first followed by the server that serves pundit.edu). If no servers are found, the default server is used. If you did not set a default, the DNR returns noNameServer. In the MacTCP Control Panel, you should enter a default domain and select the Default button.
Once a list of servers that support the domain is found, those servers are queried in the order of their distance from the querying host. First servers on the local network are queried, followed by servers on other networks. When you use the AddrToName query, you must select a default server.
6 Miscellaneous Interfaces
This chapter describes types that are found throughout the programmatic interfaces supplied with the MacTCP driver.
MacTCPCommontypes
This file defines result code name-to-number mapping, Internet Control Message Protocol (ICMP) message report structures, and other miscellaneous types throughout the MacTCP driver.
Result codes
The result codes in MacTCPCommontypes are described as follows. Chapters 3, 4, and 5 contain specific occurrences of the result codes described in this section.
#define inProgress 1 When an IOPB is still pending, ioResult is set to inProgress.
#define ipBadLapErr -23000 Unable to initialize the local network handler.
#define ipBadCnfgErr -23001 The manually set address is configured improperly.
#define ipNoCnfgErr -23002 A configuration resource is missing.
#define ipLoadErr -23003 Not enough room in the application heap (Macintosh 512K enhanced only).
#define ipBadAddr -23004 Error in getting an address from a server or the address is already in use by another machine.
#define connectionClosing -23005 A TCPClose command was already issued so there is no more data to send on this connection.
#define invalidLength -23006 The total amount of data described by the WDS was either 0 or greater than 65,535 bytes.
#define connectionExists -23007 The TCP or UDP stream already has an open connection.
#define connectionDoesntExist -23008 This TCP stream has no open connection.
#define insufficientResources -23009 64 TCP or UDP streams are already open.
#define invalidStreamPtr -23010 The specified TCP or UDP stream is not open.
#define streamAlreadyOpen -23011 An open stream is already using this receive buffer area.
#define connectionTerminated -23012 The TCP connection was broken; the reason will be given in a terminate ASR.
#define invalidBufPtr -23013 The receive buffer area pointer is 0.
#define invalidRDS -23014 The RDS refers to receive buffers not owned by the user.
#define invalidWDS -23014 The WDS pointer was 0.
#define openFailed -23015 The connection came halfway up and then failed.
#define commandTimeout -23016 The specified command action was not completed in the specified time period.
#define duplicateSocket -23017 A stream is already open using this local UDP port or a TCP connection already exists between this local IP address and TCP port, and the specified remote IP address and TCP port.
#define ipDontFragErr -23032 The packet is too large to send without fragmenting and the Don’t Fragment flag is set.
#define ipDestDeadErr -23033 The destination host is not responding to address resolution requests.
#define icmpEchoTimeoutErr -23035 The icmp echo packet was not responded to in the indicated timeout period.
#define ipNoFragMemErr -23036 Insufficient internal driver buffers available to fragment this packet on send.
#define ipRouteErr -23037 No gateway available to manage routing of packets to off-network destinations.
#define nameSyntaxErr -23041 The hostName field had a syntax error. The address was given in dot notation (that is, W.X.Y.Z) and did not conform to the syntax for an IP address.
#define cacheFault -23042 The name specified cannot be found in the cache. The domain name resolver will now query the domain name server and return the answer in the call-back procedure.
#define noResultProc -23043 No result procedure is passed to the address translation call when the resolver must be used to find the address.
#define noNameServer -23044 No name server can be found for the specified name string.
#define authNameErr -23045 This domain name does not exist.
#define noAnsErr -23046 None of the known name servers are responding.
#define dnrErr -23047 The domain name server has returned an error.
#define outOfMemory -23048 Not enough memory is available to issue the needed DNR query or to build the DNR cache.
Miscellaneous types
This section describes types that are common to all the programmatic interfaces in the MacTCP driver.
#define BYTES_16WORD 2 /* bytes per 16 bit ip word */
#define BYTES_32WORD 4 /* bytes per 32 bit ip word */
#define BYTES_64WORD 8 /* bytes per 64 bit ip word */
typedef unsigned char b_8; /* 8-bit quantity */
typedef unsigned short b_16; /* 16-bit quantity */
typedef unsigned long b_32; /* 32-bit quantity */
typedef b_32 ip_addr; /* IP address is 32-bits */
typedef b_16 ip_port
typedef struct ip_addrbytes {
union {
b_32 addr;
char byte[4];
} a;
} ip_addrbytes;
typedef struct wdsEntry {
unsigned short length; /* length of buffer */
char * ptr; /* pointer to buffer */
} wdsEntry;
typedef struct rdsEntry {
unsigned short length; /* length of buffer */
char * ptr; /* pointer to buffer */
} rdsEntry;
typedef unsigned long BufferPtr;
typedef unsigned long StreamPtr;
Internet Control Message Protocol report structures
In TCP and UDP, the ASR routine can be called with an Internet Control Message Protocol (ICMP) message. This section describes the types and structures of the ICMP messages.
typedef enum ICMPMsgType {
netUnreach, hostUnreach, protocolUnreach,
portUnreach, fragReqd, sourceRouteFailed,
timeExceeded, parmProblem, missingOption,
lastICMPMsgType = 65535
} ICMPMsgType;
typedef struct ICMPReport {
StreamPtr streamPtr;
ip_addr localHost;
ip_port localPort;
ip_addr remoteHost;
ip_port remotePort;
short reportType;
unsigned short optionalAddlInfo;
unsigned long optionalAddlInfoPtr;
} ICMPReport;
Refer to the section “UDP Asynchronous Notification Routine” in Chapter 3 and “TCP Asynchronous Notification Routine” in Chapter 4 for details on how the ICMP report structure is used.
GetMyIPAddr
This section describes how an application obtains the IP address of the machine on which it is running. GetMyIPAddr describes the parameter block that makes the PBControl call that returns the IP address and subnet mask of the local host. The csCode for this call is 15, and the driver reference number is returned from the Open Driver call.
#define ipctlGetAddr 15 /* csCode to get our IP
address */
#define IPParamBlockHeader \
struct QElem *qLink; \
short qType; \
short ioTrap; \
Ptr ioCmdAddr; \
ProcPtr ioCompletion; \
OSErr ioResult; \
StringPtr ioNamePtr; \
short ioVRefNum; \
short ioCRefNum; \
short csCode
struct IPParamBlock {
IPParamBlockHeader; /* standard I/O header */
ip_addr ourAddress; /* our IP address */
long ourNetMask; /* our IP net mask */
};
The IP address is returned in the ourAddress field and the subnet mask is returned in the ourNetMask field.
ICMP echo
The ICMP echo request message allows a host to determine whether a remote host is operational without bringing up a protocol like TCP or UDP. ICMP echo can also be used to determine the responsiveness of a network. The following interface to ICMP echo is provided:
#define ipctlEchoICMP 17
#define ipmplEchoTimeoutErr -23035
typedef void (*ICMPEchoNotifyProc)
(struct ICMPParamBlock *iopb);
The following structure is used to make the PBControl call initiate an ICMP echo request. The destination address is in the dest field, and the data to be echoed is described by wdsEntry in the data field. The specified timeout indicates how long to wait for the echo reply. The icmpCompletion routine is called either at timeout or when a packet is returned from the remote site. When a timeout occurs, the result code in the ICMPParamBlock is icmpEchoTimeoutErr. When an ICMP echo returns successfully, the time in ticks when the reply was received is contained in the echoReplyIn field. The time in ticks when the request was dispatched is contained in the echoRequestOut field. The echoed data contains the data received in the response packet.
You can send options in an echo packet by filling the options field. Options must be well-formed (see RFC 791) and terminated on a long word boundary. The length field specifies the length of the options field in bytes. The icmpCompletion routine is called with the options field set if options are found in the echo response packet. The userdata pointer can be passed into the echo call and is returned unmodified in the icmpCompletion routine.
struct IPParamBlock {
IPParamBlockHeader;
struct {
ip_addr dest;
wdsEntry data;
short timeout;
Ptr options;
unsigned short optLength;
ICMPEchoNotifyProc icmpCompletion;
unsigned long userDataPtr;
} IPEchoPB;
};
struct ICMPParamBlock {
IPParamBlockHeader;
short params [11];
struct {
unsigned long echoRequstOut;
unsigned long echoReplyIn;
struct rdsEntry echoedData;
Ptr options;
unsigned long userDataPtr;
} icmpEchoInfo;
};
Appendix Constants
This appendix presents command codes, UDP asynchronous event codes, TCP asynchronous event codes, and reasons for TCP termination.
Command codes
UDPCreate 20
UDPRead 21
UDPBfrReturn 22
UDPWrite 23
UDPRelease 24
UDPMaxMTUSize 25
UDPStatus 26
UDPMultiCreate 27
UDPMultiSend 28
UDPMultiRead 29
TCPCreate 30
TCPPassiveOpen 31
TCPActiveOpen 32
TCPSend 34
TCPNoCopyRcv 35
TCPBfrReturn 36
TCPRcv 37
TCPClose 38
TCPAbort 39
TCPStatus 40
TCPRelease 42
TCPGlobalInfo 43
UDP asynchronous event codes
data arrival 1
ICMP message received 2
TCP asynchronous event codes
closing 1
ULP timeout 2
terminate 3
data arrival 4
urgent data outstanding 5
ICMP message received 6
Reasons for TCP termination
remote abort 2
network failure 3
security/precedence mismatch 4
ULP timeout 5
ULP abort 6
ULP close 7
service failure 8
‘ ◊# ˇ ˇˇˇˇ # ◊
d , p AppleIcon p
. ° d ONLN d 6 | V ñ +önK , N Helvetica Narrow
° d ONLN d @ Æ Tî )2MacTCP Programmer’s Guide ˇ
∫ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ; F & +<c ° d ONLN d ; 0 F ä )Apple Computer, Inc.
° d ONLN d I T œ ( p <0This manual and the software described in it are ° d ONLN d H S ^ — *
0copyrighted, with all rights reserved. Under the ° d ONLN d y ] h Ó *
6copyright laws, this manual or the software may not be ° d ONLN d ∞ g r · *
4copied, in whole or part, without written consent of ° d ONLN d  q | ‰ *
5Apple, except in the normal use of the software or to ° d ONLN d { Ü Ã *
,make a backup copy of the software. The same ° d ONLN dH Ö ê „ *
4proprietary and copyright notices must be affixed to ° d ONLN d} è ö ‚ *
5any permitted copies as were affixed to the original. ° d ONLN d≥ ô § ‚ *
3This exception does not allow copies to be made for ° d ONLN dÁ £ Æ ⁄ *
4others, whether or not sold, but all of the material ° d ONLN d ≠ ∏ Ì *
6purchased (with all backup copies) may be sold, given, ° d ONLN dS ∑ ¬ „ *
3or loaned to another person. Under the law, copying ° d ONLN dá ¡ Ã Ê *
5includes translating into another language or format. ° d ONLN dΩ Œ Ÿ ‰ *
1You may use the software on any computer owned by ° d ONLN dÔ ÿ „ Í *
6you, but extra copies cannot be made for this purpose. ° d ONLN d& Â Ÿ *
1The Apple logo is a registered trademark of Apple ° d ONLN dX Ô ˙ Ÿ *
/Computer, Inc. Use of the “keyboard” Apple logo ° d ONLN dà ˘ Í *
4(Option-Shift-K) for commercial purposes without the ° d ONLN dΩ À *
-prior written consent of Apple may constitute ° d ONLN dÎ
Ÿ *
0trademark infringement and unfair competition in ° d ONLN d " † *
$violation of federal and state laws. , Helvetica ° d ONLN dA% . % *
.Apple, the Apple logo, AppleTalk, LaserWriter, ° d ONLN dÕY d Õ *
)LocalTalk, Macintosh, MacTCP, and MPW are ° d ONLN d˜c n Á *
5trademarks of Apple Computer, Inc., registered in the ° d ONLN d-m x ù *
"United States and other countries. ° d ONLN dPz Ö € *
1Simultaneously published in the United States and ° d ONLN dÇÑ è < *
Canada. ° d ONLN dãë ú „ *
4Mention of third-party products is for informational ° d ONLN d¿õ ¶ È *
4purposes only and constitutes neither an endorsement ° d ONLN dı• ∞ ª *
&nor a recommendation. Apple assumes no ° d ONLN d Ø ∫ Í *
6responsibility with regard to the performance of these ° d ONLN dSπ ƒ A *
products. ˇ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d A T T õ +rnContents , Times
° d ONLN d ß Æ ¥H +Zb!Preface: About This Guide / vii ° d ONLN d , ù ◊ ¢ ( Û ª1 ° d ONLN d . Æ ◊ ˜ )Introduction / 1 ° d ONLN d A › Æ Í/ * Architectural overview / 2
° d ONLN d ^ Ì ∫ ¯ò + 3Application, presentation, and session layers / 2 ° d ONLN d í ˚ ∫ *Transport layer / 3
° d ONLN d ® Δw + )Transmission Control Protocol (TCP) / 3 ° d ONLN d “ Δ ^ * "User Datagram Protocol (UDP) / 3
° d ONLN d ı! ∫, (H ÿNetwork layer / 4 ° d ONLN d / ∫: *Data link layer / 4 ° d ONLN d = ∫H *Physical layer / 4
° d ONLN d5^ ùk ¢ (á ª2 ° d ONLN d7^ Æk" )The MacTCP Driver / 5 ° d ONLN dOq Æ~ *The PBOpen call / 6 ° d ONLN deÉ Æê *The PBControl call / 7 ° d ONLN d~ï Æ¢ *The PBClose call / 8 ° d ONLN dïß Æ¥ *The Gestalt call / 8 ° d ONLN d¨π ÆΔ* *Implementation notes / 9
° d ONLN d«… ∫‘[ + "Fragmentation and reassembly / 9 ° d ONLN dÍ◊ ∫‚ Û *
Routing / 9
° d ONLN d˘¯ ú ¢ (! ∫3 ° d ONLN d˚¯ Æ7 ) User Datagram Protocol / 11 ° d ONLN d Æ *Data structures / 12
° d ONLN d0 ∫&5 + Write Data Structures / 12 ° d ONLN dM) ∫4- *Receive buffer area / 13
° d ONLN dh9 ÆF (b ÃUsing UDP / 13 ° d ONLN dyK ÆX *UDP routines / 14
. ° d ONLN d Ñ + Ã +¢GUDPWrite / 20 ° d ONLN d . Ñ 9 ÷ *UDPRelease / 21 ° d ONLN d " < Ñ G Õ *
UDPMTU / 21 ° d ONLN d 0 J Ñ U *UDP Multiport Create / 22 ° d ONLN d L X Ñ c ˝ *UDP Multiport Send / 23 ° d ONLN d f f Ñ q * UDP Multiport Receive / 24
° d ONLN dÆ∞ Ѫ Î (◊ ¢TCPPassiveOpen / 41 ° d ONLN dƒæ Ñ… Ë *TCPActiveOpen / 44 ° d ONLN dŸÃ Ñ◊ … *TCPSend / 45 ° d ONLN dË⁄ ÑÂ Í *TCPNoCopyRcv / 47 ° d ONLN d¸Ë ÑÛ ‡ *TCPBfrReturn / 49 ° d ONLN dˆ Ñ ¿ * TCPRcv / 50 ° d ONLN d Ñ À *TCPClose / 52 ° d ONLN d- Ñ Õ *TCPAbort / 53 ° d ONLN d= Ñ+ Õ *TCPStatus / 54 ° d ONLN dN. Ñ9 ‘ *TCPRelease / 56 ° d ONLN d`< ÑG  *TCPGlobalInfo / 57
° d ONLN duL xY (u ñ$C parameter-block definitions / 59
(Ÿ <iv
)Contents à :ÃÛ ˇ^ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d ù , ¢ +ªH5 ° d ONLN d Æ ,G )!Name-to-Address Resolution / 65 , Times ° d ONLN d $ 2 Æ ?f *'The AddressXlation.h header file / 66
° d ONLN d L B ∫ M< + The OpenResolver call / 67 ° d ONLN d i P ∫ [. *The StrToAddr call / 68 ° d ONLN d É ^ ∫ i. *The AddrToStr call / 69 ° d ONLN d ù l ∫ w4 *The EnumCache call / 70 ° d ONLN d ∑ z ∫ Ö< *The AddrToName call / 72 ° d ONLN d “ à ∫ ì *The HInfo call / 73 ° d ONLN d Ë ñ ∫ °" *The MXInfo call / 74 ° d ONLN d ˇ § ∫ Ø< * The CloseResolver call / 75
° d ONLN d ¥ Æ ¡p ( › Ã)Binding the DNR to the application / 75 ° d ONLN dG Δ Æ ” *DNR operation / 76 ° d ONLN d] È ù ˆ ¢ ( ª6 ° d ONLN d_ È Æ ˆ5 ) Miscellaneous Interfaces / 77 ° d ONLN d ¸ Æ ; *MacTCPCommontypes / 78
° d ONLN dò ∫
+ Result codes / 78 ° d ONLN d¨ ∫%0 *Miscellaneous types / 81 ° d ONLN d«( ∫3¿ *:Internet Control Message Protocol report structures / 81
° d ONLN d8 ÆE (a ÃGetMyIPAddr / 82 ° d ONLN dJ ÆW *ICMP echo / 83 ° d ONLN d'm yz ¢ (ñ óAppendix ° d ONLN d0m Æz ¯ )5Constants / 85 ° d ONLN dAÄ Æç *Command codes / 85 ° d ONLN dVí Æüa *#UDP asynchronous event codes / 85 ° d ONLN dz§ Ʊ^ *#TCP asynchronous event codes / 86 ° d ONLN dû∂ Æ√T *"Reasons for TCP termination / 86
(ŸÈContents
):v à pÃ) ˇ
~ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d A T T ì +rnPreface ° d ONLN d A Æ T4 )ZAbout This Guide , Times
° d ONLN d ™ Æ µ˛ *cFThis guide describes how to create application programs for the MacTCP ° d ONLN d ` ∏ Æ √Ó *Adriver. The MacTCP driver, Apple Computer’s implementation of the ° d ONLN d ¢ Δ Æ —˚ *Gprotocol suite known as Transmission Control Protocol/Internet Protocol ° d ONLN d Í ‘ Æ fl *D(TCP/IP), increases the Macintosh computer’s ability to operate in a ° d ONLN d/ ‚ Æ Ì` *#heterogeneous computer environment.
° d ONLN dS ˝ Æ
* What’s in this guide
° d ONLN dh Æ ¸ *IThis guide is divided into six chapters and one appendix that contain the ° d ONLN d≤# Æ. *following information: , p AppleIcon p
° d ONLN d…7 Æ? ≥ *n
° d ONLN dÀ5 ª@Â )
=Chapter 1, “Introduction,” provides an overview of the MacTCP ° d ONLN d C ªN Ù *
architecture. p
° d ONLN dW Æ_ ≥ (| Ãn
° d ONLN dU ª`˙ )
@Chapter 2, “The MacTCP Driver,” describes the PBOpen, PBControl, ° d ONLN dZc ªnfl *@PBClose, and Gestalt calls and describes internal algorithms and ° d ONLN dõq ª|B * decisions made by the driver. p
° d ONLN dπÖ Æç ≥ (™ Ãn
° d ONLN dªÉ ªéfl )
<Chapter 3, “User Datagram Protocol,” describes UDP routines. p
° d ONLN d¯ó Æü ≥ (º Ãn
° d ONLN d˙ï ª†˚ )
CChapter 4, “Transmission Control Protocol,” describes TCP routines. p
DChapter 5, “Name-to-Address Resolution,” describes how textual names ° d ONLN dÖµ ª¿< * are resolved to IP addresses. p
° d ONLN d£… Æ— ≥ (Ó Ãn
° d ONLN d•« ª“Ó )
CChapter 6, “Miscellaneous Interfaces,” describes the types that are ° d ONLN dÈ’ ª‡„ *>found throughout the programmatic interfaces supplied with the ° d ONLN d(„ ªÓ *MacTCP driver. p
° d ONLN d7˜ Æˇ ≥ ( Ãn
° d ONLN d9ı ª “ )
6The Appendix, “Constants,” presents command codes, UDP ° d ONLN dp ª *Casynchronous event codes, TCP asynchronous event codes, and reasons ° d ONLN d¥ ª *for TCP termination.
° d ONLN d…, Æ9@ (U ÃWho should read this guide
° d ONLN d‰D ÆOÎ *AThis guide is designed both for Macintosh programmers who are not ° d ONLN d&R Æ]
*Ifamiliar with TCP/IP and for TCP/IP programmers who are not familiar with ° d ONLN dp` Ækr *&the Macintosh programming environment. à pÃ) ˇå ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d x , Û +ñHDocument conventions , Times
° d ONLN d 7 x B¡ *@This document reflects the Macintosh Programmer’s Workshop (MPW) ° d ONLN d V E x Pr *8conventions for types and sizes of variables and fields.
° d ONLN d è ` x m › * Related documents
° d ONLN d ° x x É{ *8You might find the following reference materials useful. , p AppleIcon p
° d ONLN d ⁄ å x î } *n
° d ONLN d ‹ ä Ö ï )
MacTCP Administrator’s Guide p
° d ONLN d ˘ û x ¶ } ( √ ñn
° d ONLN d ˚ ú Ö ß ◊ )
Inside Macintosh, ° d ONLN d ú ◊ ß )R
Volumes I–VI p
° d ONLN d ∞ x ∏ } ( ’ ñn
° d ONLN d Æ Ö π “ )
Douglas Comer, ° d ONLN d+ Æ “ πY )M Internetworking with TCP/IP, ° d ONLN dG ÆY πœ )á Second Edition (Prentice ° d ONLN d` Æœ π” )v- ° d ONLN da º Ö « π ( „ £ Hall, 1991) p
° d ONLN dm – x ÿ } ( ı ñn
° d ONLN do Œ Ö Ÿ— )
DThe MacTCP driver implements protocols that conform to the following ° d ONLN d¥ ‹ Ö Áµ *<Request for Comments (RFC) and Military Standards (MIL-STD): ° d ONLN dÒ Í Ö ı3 *!—RFC 768 (User Datagram Protocol) ° d ONLN d ¯ Öx */—RFC 791, 894; MIL-STD 1777 (Internet Protocol) ° d ONLN dC Öb *,—RFC 792 (Internet Control Message Protocol) ° d ONLN dp Ö † *6—RFC 793; MIL-STD 1778 (Transmission Control Protocol) ° d ONLN dß" Ö-G *&—RFC 826 (Address Resolution Protocol) ° d ONLN dŒ0 Ö;m *.—RFC 903 (Reverse Address Resolution Protocol) ° d ONLN d˝> ÖI * —RFC 950 (Internet Subnetting) ° d ONLN d L ÖW7 *#—RFC 951, 1048 (Bootstrap Protocol) ° d ONLN d@Z ÖeR *'—IDEA004 (Routing Information Protocol) ° d ONLN dhh ÖsH *%—RFC 1010 (Internet Assigned Numbers) ° d ONLN dév ÖÅT *&—RFC 1034, 1035 (Domain Name Resolver) ° d ONLN dµÑ Öè! * —RFC 1060 (Assigned Numbers) ° d ONLN d“í Öù‘ *@—RFC 1122 (Requirements for Internet Hosts—Communication Layers)
(Ÿ <viii
)Preface à :ÃÛ ˇ¯ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
0 . ° d ONLN d * T Z j +rn1
° d ONLN d A Æ T )Z Introduction , Times
° d ONLN d ™ Æ µË *cBThe MacTCP driver is a software driver for the Macintosh Operating ° d ONLN d R ∏ Æ √ *JSystem that allows developers to create Macintosh applications for network ° d ONLN d ù Δ Æ — *Ienvironments that use the Transmission Control Protocol/Internet Protocol ° d ONLN d Á ‘ Æ fl· *B(TCP/IP). TCP/IP is a widely used industry standard for connecting ° d ONLN d* ‚ Æ Ì¸ *Fmultivendor computers. The TCP/IP protocol layers are fully compatible ° d ONLN dq Æ ˚È *Dacross all implementations on different hardware platforms, allowing ° d ONLN d∂ ˛ Æ
*Kdifferent vendors’ computers that run TCP/IP to interoperate and share data ° d ONLN d Æ Ë *
and services. ° d ONLN d! Æ,œ *=This chapter provides an overview of the MacTCP architecture. à pÃ) ˇ}¶ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - ë +<IArchitectural overview , Times
ˇˇ ˇ ˇ ˇˇ˛ ˇˇ ˇ˚ ˇˇ ˇ ˇ˛ ˇˇ ˇˇ˛ ˇ ˛ˇÛ ˇÙ‡ ˇ˝ ˇ ˇ ˇ ˇˇ ˇ˝ ˇ ˛ˇ ˇ¬ ë ÚˇÊ ˇÛ ˇ⁄ Úˇ• Å Á ˇÛ ˇÅ Ô Å Å ≈ Å Å ≈
< ° d
ONLN f §
ù êÉÀ < ° d
ONLN f Z
. Ê; Ê; ( ù ê † æ † ¬ † ø ) ° d
ONLN f ≤4
d
. ° d ONLN di xt û +Û
Figure 1-1 ° d ONLN di ût> )&) MacTCP protocols and OSI network layers
° d ONLN d8à xì« (Ø ñGThe TCP/IP protocols shown in Figure 1-1 are described in the following ° d ONLN dÄñ x° ü * sections.
° d ONLN dä± xæd * -Application, presentation, and session layers
° d ONLN d∏… x‘æ *HServices in the upper-layer protocols such as the File Transfer Protocol ° d ONLN d◊ x‚ *F(FTP), Telnet, and the Simple Mail Transfer Protocol (SMTP) correspond ° d ONLN dHÂ x¡ *Ito the application, presentation, and session layers of the OSI model. As ° d ONLN díÛ x˛Õ *Lindicated in Figure 1-1, such services are typically developer products that ° d ONLN dfl x Ø *Baugment the services of TCP, IP, and the User Data Protocol (UDP).
° ¿ 0 i ° ¿ ° ¿ 0 J ° ¿ ° ¿ 0 j ° ¿ ° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿ [ ° ¿ ]0 d ° ¿
° ¿ %AI3_Note:
° ¿ 0 D
° ¿ 444.8712 563.0014 m
° ¿ 444.8712 592.9706 L
° ¿ 194.5991 592.9706 L
° ¿ 194.5991 563.0014 L
° ¿ 444.8712 563.0014 L
° ¿ b
° ¿ 319.9851 577.486 m
° ¿ B
° ¿ U
° ¿ u
° ¿ 0.8 g
° ¿ 444.8712 449.7613 m
° ¿ 444.8712 592.986 L
° ¿ 378.5 592.986 L
° ¿ 378.5 563.0014 L
° ¿ 194.5991 563.0014 L
° ¿ 194.5991 449.7613 L
° ¿ 444.8712 449.7613 L
° ¿ b
° ¿ 319.9851 462.4615 m
° ¿ B
° ¿ U
° ¿ u
° ¿ 1 g
° ¿ 256.5237 568.6055 m
° ¿ 256.5237 586.3665 L
° ¿ 202.7997 586.3665 L
° ¿ 202.7997 568.6055 L
° ¿ 256.5237 568.6055 L
° ¿ b
° ¿ 229.6403 577.486 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.1655 0 0 1.1655 229.6403 574.4334 0 Tp
° ¿ TP
° ¿ -5.98 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ /_Helvetica-Narrow 7.722 Tf
° ¿ 0 Ts
° ¿ 100 Tz
° ¿ 0 Tt
° ¿ 0 TA
° ¿ 0 0 5 TC
° ¿ 100 100 200 TW
° ¿ 0 0 0 Ti
° ¿ 1 Ta
° ¿ 0 Tq
° ¿ 9.438 0 Tl
° ¿ 0 Tc
° ¿ 0 Tw
° ¿ (FTP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 315.0493 568.6055 m
° ¿ 315.0493 586.3665 L
° ¿ 261.2826 586.3665 L
° ¿ 261.2826 568.6055 L
° ¿ 315.0493 568.6055 L
° ¿ b
° ¿ 288.166 577.486 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ (1.1655 0 0 1.1655 288.166 574.4334 0 Tp
° ¿ TP
° ¿
-8.7956 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (Telnet) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 373.5321 568.6055 m
° ¿ 373.5321 586.3665 L
° ¿ 319.8083 586.3665 L
° ¿ 319.8083 568.6055 L
° ¿ 373.5321 568.6055 L
° ¿ b
° ¿ 346.6917 577.486 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.1655 0 0 1.1655 346.6917 574.4334 0 Tp
° ¿ TP
° ¿
-8.7937 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (SMTP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 313.3687 540.5124 m
° ¿ 313.3687 558.2733 L
° ¿ 202.988 558.2733 L
° ¿ 202.988 540.5124 L
° ¿ 313.3687 540.5124 L
° ¿ b
° ¿ 258.1487 549.3928 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 257.8637 546.3402 0 Tp
° ¿ TP
° ¿
-4.7101 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ 74.4019 Tz
° ¿ (TCP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 540.5124 m
° ¿ 436.5012 558.2733 L
° ¿ 326.1206 558.2733 L
° ¿ 326.1206 540.5124 L
° ¿ 436.5012 540.5124 L
° ¿ b
° ¿ 381.3408 549.3928 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 381.6257 546.3402 0 Tp
° ¿ TP
° ¿ -4.971 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (UDP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 515.6154 m
° ¿ 436.5012 533.3762 L
° ¿ 202.988 533.3762 L
° ¿ 202.988 515.6154 L
° ¿ 436.5012 515.6154 L
° ¿ b
° ¿ 319.7447 524.4958 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 521.4431 0 Tp
° ¿ TP
° ¿
-2.2253 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (IP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 275.1983 482.4852 m
° ¿ 275.1983 494.1929 L
° ¿ 202.988 494.1929 L
° ¿ 202.988 482.4852 L
° ¿ 275.1983 482.4852 L
° ¿ b
° ¿ 239.0644 488.3391 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 239.0644 485.3111 0 Tp
° ¿ TP
° ¿
-6.0223 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (ALAP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 355.8785 482.4852 m
° ¿ 355.8785 494.1929 L
° ¿ 283.6108 494.1929 L
° ¿ 283.6108 482.4852 L
° ¿ 355.8785 482.4852 L
° ¿ b
° ¿ 319.7447 488.3391 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 485.3111 0 Tp
° ¿ TP
° ¿
-6.0223 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (ELAP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 482.4852 m
° ¿ 436.5012 494.1929 L
° ¿ 364.2912 494.1929 L
° ¿ 364.2912 482.4852 L
° ¿ 436.5012 482.4852 L
° ¿ b
° ¿ 400.4251 488.3391 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 400.4251 485.3111 0 Tp
° ¿ TP
° ¿
-5.8905 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (TLAP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 275.1983 456.5002 m
° ¿ 275.1983 474.261 L
° ¿ 202.988 474.261 L
° ¿ 202.988 456.5002 L
° ¿ 275.1983 456.5002 L
° ¿ b
° ¿ 239.0644 465.3806 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 239.0644 462.3279 0 Tp
° ¿ TP
° ¿ -9.847 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (LocalT) ° ¿ Tx ° ¿ 0 80 ° ¿ Tk ° ¿
° ¿ (alk) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 355.8785 456.5002 m
° ¿ 355.8785 474.261 L
° ¿ 283.6108 474.261 L
° ¿ 283.6108 456.5002 L
° ¿ 355.8785 456.5002 L
° ¿ b
° ¿ 319.7447 465.3806 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 462.3279 0 Tp
° ¿ TP
° ¿
-8.9013 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿
(Ethernet) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 456.5002 m
° ¿ 436.5012 474.261 L
° ¿ 364.2912 474.261 L
° ¿ 364.2912 456.5002 L
° ¿ 436.5012 456.5002 L
° ¿ b
° ¿ 400.4251 465.3806 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 400.4251 462.3279 0 Tp
° ¿ TP
° ¿ -12.0405 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (Token Ring) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 496.5269 m
° ¿ 436.5012 508.3534 L
° ¿ 202.988 508.3534 L
° ¿ 202.988 496.5269 L
° ¿ 436.5012 496.5269 L
° ¿ b
° ¿ 319.7447 502.4402 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 498.8771 0 Tp
° ¿ TP
° ¿ -21.8556 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (Link Access Protocol) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 10 M ° ¿
° ¿ 240.6311 456.5822 m
° ¿ 240.6311 438.3615 l
° ¿ S
° ¿ 319.7447 456.5822 m
° ¿ 319.7447 438.3615 l
° ¿ S
° ¿ 400.4251 456.5822 m
° ¿ 400.4251 438.3615 l
° ¿ S
° ¿ u
° ¿ 0 O
° ¿ 1 g
° ¿ 0.5 w ° ¿
° ¿ 275.1983 433.2045 m
° ¿ 275.1983 444.9122 L
° ¿ 202.988 444.9122 L
° ¿ 202.988 433.2045 L
° ¿ 275.1983 433.2045 L
° ¿ b
° ¿ 239.0644 439.0584 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 239.0644 435.9476 0 Tp
° ¿ TP
° ¿
-5.7579 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (.MPP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 355.8785 433.2045 m
° ¿ 355.8785 444.9122 L
° ¿ 283.6108 444.9122 L
° ¿ 283.6108 433.2045 L
° ¿ 355.8785 433.2045 L
° ¿ b
° ¿ 319.7447 439.0584 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 435.9476 0 Tp
° ¿ TP
° ¿
-6.9355 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (.ENET) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 433.2045 m
° ¿ 436.5012 444.9122 L
° ¿ 364.2912 444.9122 L
° ¿ 364.2912 433.2045 L
° ¿ 436.5012 433.2045 L
° ¿ b
° ¿ 400.4251 439.0584 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 400.4251 435.9476 0 Tp
° ¿ TP
° ¿ -14.3927 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (.TOKN driver ) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 275.1983 406.5962 m
° ¿ 275.1983 430.4769 L
° ¿ 202.988 430.4769 L
° ¿ 202.988 406.5962 L
° ¿ 275.1983 406.5962 L
° ¿ b
° ¿ 239.0644 418.5366 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 239.0644 416.7989 0 Tp
° ¿ TP
° ¿ -4.971 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (SCC) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 355.8785 406.5962 m
° ¿ 355.8785 430.4769 L
° ¿ 283.6108 430.4769 L
° ¿ 283.6108 406.5962 L
° ¿ 355.8785 406.5962 L
° ¿ b
° ¿ 319.7447 418.5366 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 319.7447 421.1697 0 Tp
° ¿ TP
° ¿
-8.9013 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿
(Ethernet) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ 4.3209 -9.438 Td
° ¿ (card) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.5012 406.5962 m
° ¿ 436.5012 430.4769 L
° ¿ 364.2912 430.4769 L
° ¿ 364.2912 406.5962 L
° ¿ 436.5012 406.5962 L
° ¿ b
° ¿ 400.4251 418.5366 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.5665 0 0 1.1655 400.4251 421.1697 0 Tp
° ¿ TP
° ¿ -12.0405 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ (Token Ring) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ 7.4601 -9.438 Td
° ¿ (card) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ )1.1655 0 0 1.1655 263.9793 387.9291 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ 100 Tz
° ¿ 0 Ta
° ¿ (Developer products) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 1 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 436.6007 568.6055 m
° ¿ 436.6007 586.3665 L
° ¿ 382.834 586.3665 L
° ¿ 382.834 568.6055 L
° ¿ 436.6007 568.6055 L
° ¿ b
° ¿ 409.7174 577.486 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.1655 0 0 1.1655 409.7174 574.4334 0 Tp
° ¿ TP
° ¿
-9.1444 0 Td
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ 1 Ta
° ¿ (SNMP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ [ ° ¿ 6 ° ¿ 2 ° ¿ ]0 d ° ¿
° ¿ 194.5991 537.0014 m
° ¿ 444.8712 537.0014 l
° ¿ S
° ¿ 378.5 563.0014 m
° ¿ 444.8712 563.0014 l
° ¿ S
° ¿ 194.5991 512.0014 m
° ¿ 444.8712 512.0014 l
° ¿ S
° ¿ 194.5991 477.5014 m
° ¿ 444.8712 477.5014 l
° ¿ S
° ¿ 0 To
° ¿ 1 0 0 1 142 586.5 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿ [ ° ¿ ]0 d ° ¿
° ¿ /_Helvetica-Narrow 9 Tf
° ¿ 0 Ta
° ¿ 11 0 Tl
° ¿
(Application) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ T*
° ¿ (Presentation) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ T*
° ¿ (Session) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 142 547.5 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ (Transport) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 142 522 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ (Network) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 142 492 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ (Data Link) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 142 440.5 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿
(Physical) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 194.5991 563.0014 m
° ¿ 8192.6681 563.0014 191.1026 564.5669 191.1026 566.4981 C
° ¿ 191.1026 589.4738 L
° ¿ 7191.1026 591.405 192.6681 592.9706 194.5991 592.9706 C
° ¿ S
° ¿ U
° ¿ 191.1026 578.7142 m
° ¿ 184.9075 578.7142 l
° ¿ S
° ¿ u
° ¿ 194.5991 537.0014 m
° ¿ 8192.6681 537.0014 191.1026 538.5669 191.1026 540.4981 C
° ¿ 191.1026 559.5046 L
° ¿ 8191.1026 561.4358 192.6681 563.0014 194.5991 563.0014 C
° ¿ S
° ¿ U
° ¿ 191.1026 549.745 m
° ¿ 175.505 549.745 l
° ¿ S
° ¿ u
° ¿ 194.5991 512.0014 m
° ¿ 8192.6681 512.0014 191.1026 513.5669 191.1026 515.4981 C
° ¿ 191.1026 533.5046 L
° ¿ 8191.1026 535.4358 192.6681 537.0014 194.5991 537.0014 C
° ¿ S
° ¿ U
° ¿ 191.1026 524.245 m
° ¿ 172.505 524.245 l
° ¿ S
° ¿ u
° ¿ 194.5991 477.5014 m
° ¿ 8192.6681 477.5014 191.1026 479.0669 191.1026 480.9981 C
° ¿ 191.1026 508.5046 L
° ¿ 8191.1026 510.4358 192.6681 512.0014 194.5991 512.0014 C
° ¿ S
° ¿ U
° ¿ 191.1026 494.495 m
° ¿ 174.505 494.495 l
° ¿ S
° ¿ u
° ¿ 194.5991 406.5014 m
° ¿ 8192.6681 406.5014 191.1026 408.0669 191.1026 409.9981 C
° ¿ 191.1026 474.0046 L
° ¿ 8191.1026 475.9358 192.6681 477.5014 194.5991 477.5014 C
° ¿ S
° ¿ U
° ¿ 191.1026 442.995 m
° ¿ 171.505 442.995 l
° ¿ S
° ¿ u
° ¿ 0 O
° ¿ 0.4 g
° ¿ 260 386.5 m
° ¿
260 396 L
° ¿
246 396 L
° ¿ 246 386.5 L
° ¿ 260 386.5 L
° ¿ b
° ¿
253 391.25 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ )1.1655 0 0 1.1655 360.9793 387.9291 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ /_Helvetica-Narrow 7.722 Tf
° ¿ 9.438 0 Tl
° ¿ (MacTCP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ u
° ¿ 0.8 g
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿
° ¿ 357 386.5 m
° ¿
357 396 L
° ¿
343 396 L
° ¿ 343 386.5 L
° ¿ 357 386.5 L
° ¿ b
° ¿
350 391.25 m
° ¿ B
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 142 603.993 0 Tp
° ¿ TP
° ¿ 0 Tr
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ /_Helvetica-Narrow-Bold 9 Tf
° ¿ 11 0 Tl
° ¿ (OSI model) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 319.9851 603.993 0 Tp
° ¿ TP
° ¿ -11.8894 0 Td
° ¿ 0 Tr
° ¿ 1 Ta
° ¿ (TCP/IP) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ %%PageTrailer
° ¿
%%Trailer
° ¿ +Adobe_IllustratorA_AI3 /terminate get exec
° ¿ )Adobe_typography_AI3 /terminate get exec
° ¿ &Adobe_customcolor /terminate get exec
° ¿ Adobe_cshow /terminate get exec
° ¿ $Adobe_cmykcolor /terminate get exec
° ¿ &Adobe_packedarray /terminate get exec
° ¿ %%EndDocument
† ø ¨ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d Æ , ˚ +ÃHTransport layer , Times
° d ONLN d 7 Æ B *IThe TCP and UDP provide services at the transport layer of the OSI model.
° d ONLN d Z Q Æ ^X * #Transmission Control Protocol (TCP)
° d ONLN d ~ h Æ s˛ *HThe Transmission Control Protocol provides reliable transmission of data ° d ONLN d « v Æ Å˛ *Mbetween processes. It ensures that data is delivered error free, without loss ° d ONLN d Ñ Æ èA * or duplication, and in sequence. ° d ONLN d6 ô Æ § *JUpper-layer protocols such as Telnet pass data to TCP for delivery to peer ° d ONLN dÅ ß Æ ≤ *Jprocesses. TCP encapsulates the data into segments and passes the segments ° d ONLN dà µ Æ ¿¸ *Hto IP, which puts the segments into datagrams and passes them across the ° d ONLN d √ Æ Œ¯ *Hinternet. TCP at the receiving end checks for errors, acknowledges error ° d ONLN d] √¯ Œ¸ ( Í- ° d ONLN d^ — Æ ‹¯ ( ¯ ÃGfree segments, and reassembles the segments for delivery to upper-layer ° d ONLN d¶ fl Æ Í *Lprotocols. If a segment is lost or damaged, it will not be acknowledged, and ° d ONLN dÛ Ì Æ ¯O *$the sending process will retransmit. ° d ONLN d Æ
˚ *FTCP has a flow control mechanism so that computers of different speeds ° d ONLN d_ ÆÈ *Aand sizes can communicate. When TCP at the receiving end sends an ° d ONLN d° Æ)ˇ *Iacknowledgment, it also advertises how much data it is prepared to accept ° d ONLN dÎ, Æ7! *on the next transmission.
° d ONLN dF ÆS< * User Datagram Protocol (UDP)
° d ONLN d"] ÆhÔ *BThe User Datagram Protocol specifies how application programs send ° d ONLN dek Æv *Hdatagrams to other application programs and defines the use of UDP ports ° d ONLN dÆy ÆÑfi *@to distinguish among multiple processes in a single machine. UDP ° d ONLN dÔá ÆíÆ *7messages are encapsulated in IP datagrams for delivery. ° d ONLN d(ú ÆßÚ *GUDP data transmission does not provide reliability. It does not provide ° d ONLN dp™ Ƶı *Gerror checking, it does not acknowledge that data has been successfully ° d ONLN d∏∏ Æ√ˇ *Freceived, and it does not order incoming messages. UDP messages can be ° d ONLN dˇΔ Æ—y *.lost or duplicated or can arrive out of order. ° d ONLN d.€ ÆÊ *JThe advantage of UDP is that the overhead associated with establishing and ° d ONLN dyÈ ÆÙ˙ *Gmaintaining an error-free TCP session is avoided. Upper-layer protocols ° d ONLN d¡˜ Æı *Jthat don’t require reliability use UDP to transmit data. For instance, the ° d ONLN d Æ *Ldomain name system uses UDP because reliability is not critical; if there is ° d ONLN dY Æ Ì *Dno response to a domain name query, the resolver simply retransmits. +ÁüArchitectural overview
)o3 à pÃ) ˇ& ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d x , Ω +ñH
Network layer , Times
° d ONLN d 7 x B— *LThe Internet Protocol (IP) provides services at the network layer of the OSI ° d ONLN d [ E x P∏ *Fmodel. IP is responsible for sending data across multiple networks. IP ° d ONLN d ¢ S x ^π *Daccepts segments of data from TCP or UDP, places the data in packets ° d ONLN d Á a x l‘ *Lcalled datagrams, and determines the correct path for the datagrams to take. ° d ONLN d4 o x z∞ *CDatagrams are sent across the internet, through as many gateways as ° d ONLN dx } x àE *.needed, until they reach the destination host. ° d ONLN dß í x ù‘ *IIP provides an addressing mechanism that allows routing between networks. ° d ONLN dÒ † x ´ª *EThe header of an IP datagram contains source and destination internet ° d ONLN d7 Æ x πà *Laddresses so that any host in a network can route a packet to a destination, ° d ONLN dÑ º x « *%either directly or through a gateway. ° d ONLN d™ — x ‹∞ *GIP has the ability to fragment a datagram as it is transmitted across a ° d ONLN dÚ fl x ͱ *Bnetwork. Since IP can be used with many different physical network ° d ONLN d5 Ì x ¯≥ *Fimplementations that specify different sizes for physical data frames, ° d ONLN d| ˚ xà *Idatagrams can be fragmented to fit into a small data frame. Fragments are ° d ONLN dΔ xD *.reassembled as they arrive at the destination. ° d ONLN dˆ x)» *KIP is often referred to as an unreliable delivery system because it makes a ° d ONLN dB, x7… *Lbest-effort attempt to deliver all datagrams, but delivery is not guaranteed ° d ONLN dè: xE“ *M(TCP guarantees delivery). It is also called a connectionless delivery system ° d ONLN d›H xS— *Jbecause it routes each datagram separately. When IP receives a sequence of ° d ONLN d(V xa∏ *Bdatagrams from TCP or UDP, it routes each datagram in the sequence ° d ONLN dkd xoº *Gindividually, and each datagram may travel over a different path to the ° d ONLN d≥r x} ≠ * destination.
° d ONLN d¿ç xö ¡ * Data link layer
° d ONLN d–• x∞ æ *
The AppleTalk ° d ONLN d›• æ∞ ¡ )F ° d ONLN dfi• ¡∞ƒ )4Link Access Protocol (ALAP) and Ethernet Link Access ° d ONLN d≥ xæ… (⁄ ñIProtocol (ELAP) provide services at the data link layer of the OSI model. ° d ONLN d]¡ xÃ∏ *AALAP and ELAP provide best-effort delivery of information between ° d ONLN düœ x⁄º *Fdevices. They provide the basic service of packet transmission between ° d ONLN dÊ› xËQ */devices connected to a single physical network. ° d ONLN dÚ x˝Æ *CThe MacTCP driver allows for the addition of other data link layers ° d ONLN dZ x *Kthrough the use of a link layer interface between the IP layer and the data ° d ONLN d¶ xs *8link layer. This interface is described in the document ° d ONLN dfis» )˚Building Alternate ° d ONLN dÒ x'= (C ñ'Link Access Protocol Modules for MacTCP ° d ONLN d ='“ )≈ available in the Developer’s CD ° d ONLN d9* x5< (Q ñ(Series from the Apple Developer’s Group.
° d ONLN dbE xR ø * Physical layer
° d ONLN dq] xhÕ *HThe MacTCP driver operates networks in which the physical layer uses the ° d ONLN d∫k xvê *;LocalTalk cable system or the Ethernet networking standard.
° d ONLN d ™ Æ µ’ *c=The MacTCP driver is a Macintosh Operating System driver that ° d ONLN d R ∏ Æ √ *Himplements the Internet Protocol (IP), User Datagram Protocol (UDP), and ° d ONLN d õ Δ Æ —ˇ *FTransmission Control Protocol (TCP). A part of the Macintosh Operating ° d ONLN d ‚ ‘ Æ fl˜ *BSystem called the Device Manager coordinates communication between ° d ONLN d% ‚ Æ ÌV *#applications and the MacTCP driver. ° d ONLN dI ˜ ÆÛ *DThe MacTCP driver resides in the Macintosh System Folder. At startup ° d ONLN dé Ɖ *Dtime, the MacTCP driver registers itself with the Device Manager as ,
Courier
° d ONLN d“‰˝ (,.IPP.
° d ONLN dÿ! Æ, (H ÃHThe MacTCP driver supports the following low-level Device Manager calls: , p AppleIcon p
° d ONLN d!5 Æ= ≥ *n
° d ONLN d#3 ª> · )
PBOpen p
° d ONLN d*G ÆO ≥ (l Ãn
° d ONLN d,E ªP Î )
PBControl p
° d ONLN d6Y Æa ≥ (~ Ãn
° d ONLN d8W ªb · )
PBClose à pÃ) ˇ
Ç ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - t +<IThe PBOpen call , Times
° d ONLN d 8 x Cà +ZGBefore the application can exchange information with the MacTCP driver, ° d ONLN d X F x Q« *Ethe driver must be opened using the Device Manager PBOpen call, which ° d ONLN d û T x _» *Jopens the driver and returns its reference number. All subsequent calls to ° d ONLN d È b x m! *%the driver use this reference number. ° d ONLN d w x ÇΔ *EThe MacTCP driver uses the INIT-31 mechanism to automatically install ° d ONLN dU Ö x ê… *Mitself in the device table and load itself into the system heap each time the ° d ONLN d£ ì x û∞ *Fmachine is restarted. At load time, all internal buffers needed by the ° d ONLN dÍ ° x ¨¡ *FMacTCP driver are also allocated on the system heap. These buffers are ° d ONLN d1 Ø x ∫ü *=used (among other things) to hold incoming fragments awaiting ° d ONLN do Ω x »Œ *Ereassembly and outgoing fragments following fragmentation. The amount ° d ONLN dµ À x ÷´ *Aof buffer space allocated is based on the amount of memory in the ° d ONLN d˜ Ÿ x ‰ ¢ *machine. ° d ONLN d Ó x ˘ƒ *FThe MacTCP driver performs its initialization sequence at PBOpen time. ° d ONLN dG ¸ x *LThe initialization sequence includes initializing the local network handler, ° d ONLN dî
x∂ *Isetting its local address and subnet mask, verifying that this address is ° d ONLN dfi x#« *Greasonable and unused, and starting up the internal TCP/IP/UDP protocol ° d ONLN d&& x1Δ *Hmachinery. PBOpen returns with an error code if any step in this process ° d ONLN do4 x?Δ *Lfails. In almost all cases, if PBOpen fails, the driver must be reconfigured ° d ONLN dºB xM– *Jand the system then restarted to clear the problem. Very few circumstances ° d ONLN dP x[n *5exist where transitory problems cause PBOpen to fail. ° d ONLN d=e xp– *HUse the reference number returned from the PBOpen call in all subsequent ° d ONLN dÜs x~Ä *=PBControl calls to this drive. Also assign this value to the ,
Courier
° d ONLN d√rÄ~∂ (öû ioCRefNum
° d ONLN dÃs∂~— )6 field. ° d ONLN d‘à xìÀ (Ø ñGBecause of the complexity of initializing the MacTCP driver, PBOpen can ° d ONLN d ñ x°± *Creturn errors from many parts of the system, including the Resource ° d ONLN d`§ xØ¿ *BManager, Device Manager, File Manager, Slot Manager, and AppleTalk ° d ONLN d£≤ xΩ ñ *driver.
(Ÿ <6
) Chapter 2 / The MacTCP Driver à :ÃÛ ˇ
Ë ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - ¥ +rIThe PBControl call , Times
° d ONLN d 8 Æ CÎ +ZBThe Device Manager PBControl call sends control information in the ° d ONLN d V F Æ Qf *(following parameter block to the driver: ,
Courier
° d ONLN d W Æ c *struct CntrlParam { ° d ONLN d î e à qD + struct QElem *qLink; ° d ONLN d ™ s à * short qType; ° d ONLN d ∏ Å Ã ç *
short csCode; ° d ONLN dD Ò Ã ˝8 *short csParam[11]; ° d ONLN dW ˇ Æ ¥ (' Ã}
° d ONLN dY Æ *In this parameter block
° d ONLN dq @ )ncsCode
° d ONLN dw@ )$, specifies the type of information sent. The ° d ONLN d§# Æ.‚ (J Ã>MacTCP driver decides what to do based on the procedure number ° d ONLN d„1 Æ< È *
specified by
° d ONLN d0 È<
);csCode
° d ONLN dˆ1
<À )$( (the Appendix lists procedure numbers). ° d ONLN d F ÆQ¸ (m ÃDAll UDP and TCP routines documented in this guide are implemented as ° d ONLN ddT Æ_€ *>Device Manager Control calls. All MacTCP routines support both ° d ONLN d£b Æmd *#synchronous and asynchronous modes. ° d ONLN d«w ÆÇ
*OIf a synchronous call is made, the application can’t continue until the call is ° d ONLN dÖ Æê˝ *Jcompleted. When control is returned to the application, the result code in ° d ONLN dbì ÆûÎ *Ithe parameter block is set indicating the success or failure of the call. ° d ONLN d≠® Æ≥
*OIf the call is asynchronous, the I/O request is placed on the driver I/O queue, ° d ONLN d˝∂ Æ¡˛ *Hand control is returned to the calling program almost immediately. While ° d ONLN dFƒ Æœ˝ *Irequests are taken from the driver I/O queue one at a time and processed, ° d ONLN dê“ Æ› *Lthe application is free to perform other tasks. The application has two ways ° d ONLN d›‡ ÆÎÉ *,of knowing when the call has been completed: , p AppleIcon p
° d ONLN d
٠Ƹ ≥ *n
° d ONLN d Ú ª˝ )
By polling the
° d ONLN dÒ ˝0 )EioResult
° d ONLN d#Ú0˝ )0. field in the parameter block. When this value ° d ONLN dR ª ˝ (' Ÿ
changes from
° d ONLN d_ˇ ˝ 9 )B
InProgress
° d ONLN di 9 Á )<' to some other value, the call has been ° d ONLN dë ª Ó (5 Ÿ
completed. p
° d ONLN dú" Æ* ≥ (G Ãn
° d ONLN dû ª+ )
GBy specifying an I/O completion routine to be called when the requested ° d ONLN dÊ. ª9! *operation is complete. ° d ONLN d˝C ÆN √ (j ÃThe
° d ONLN dB √N ) ioCompletion
° d ONLN d
C N˜ )H5 field in the parameter block contains a pointer to a ° d ONLN dCQ Æ\ (x ÃIcompletion routine to be executed at the end of an asynchronous call. The
° d ONLN dç^ Æj ˆ * ioCompletion
° d ONLN dô_ ˆj‰ )H3 field should be NIL for asynchronous calls with no ° d ONLN dÕm ÆxÛ (î ÃFcompletion routine and is automatically set to NIL for all synchronous ° d ONLN d{ ÆÜ ≈ *calls.
+˝7The PBControl call
)Y7 à pÃ) ˇ Œ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x , “ +ñHThe driver uses the ,
Courier
° d ONLN d “ , )Z ioNamePtr
° d ONLN d ! , )6 and
° d ONLN d " ,U ) ioVRefNum
° d ONLN d + !U ,£ )6 fields internally. ° d ONLN d ? 6 x A… ( ] ñFEach routine description includes a parameter block format. The number ° d ONLN d Ü D x OÀ *Mnext to each field name indicates the byte offset of the field from the start ° d ONLN d ‘ R x ]– *Hof the parameter block pointed to by A0. An arrow next to each parameter ° d ONLN d ` x kø *Hname indicates whether it’s an input, output, or input/output parameter: ° d ONLN df x x É î *Arrow ° d ONLN dl x “ É ¸ )ZMeaning , Symbol ° d ONLN dt å x ò É ( ¥ ñÆ ° d ONLN dv ç “ òo )Z#Parameter is passed to the routine. ° d ONLN dö ° x ≠ É ( … ñ¨ ° d ONLN dú ¢ “ ≠{ )Z%Parameter is returned by the routine. ° d ONLN d¬ ∂ x ¬ É ( fi ñ´ ° d ONLN dƒ ∑ “ ¬º )Z3Parameter is passed to and returned by the routine. ° d ONLN d¯ ” x fi∫ ( ˙ ñFAll Device Manager Control calls return an integer result code of type
° d ONLN d? ‡ x Ï ñ *OSErr
° d ONLN dD · ñ Ï ∂ ) in the
° d ONLN dL ‡ ∂ Ï Ê ) ioResult
° d ONLN dT · Ê Ïº )0/ field of the I/O parameter block. Each routine ° d ONLN dÑ Ô x ˙— ( ñLdescription lists all of the applicable result codes generated by the MacTCP ° d ONLN d— ˝ xÆ *Edriver, along with a short description of what the result code means. , N Helvetica Narrow
° d ONLN d1• x∞… +ZIThe Gestalt call is used to obtain MacTCP driver version information (see ° d ONLN d{≥ xæ@ **the chapter “Compatibility Guidelines” in ° d ONLN d•≥@æè )»Inside Macintosh ° d ONLN dµ≥èæœ )O
, Volume VI). ° d ONLN d√¡ xë (Ë ñHTo make the Gestalt call, use the mtcp selector. If you are using MacTCP ° d ONLN d œ x⁄∂ *Idriver version 1.1, a value of 1 is returned in the response field of the ° d ONLN dV› xË≈ *MGestalt call. If yu are using version 1.1.1, a value of 2 is returned. If you ° d ONLN d§Î xˆƒ *Lare using version 2.0, a value of 3 is returned. A value of 0 is returned if ° d ONLN dÒ˘ x Ë *the driver is not opened.
(Ÿ <8
) Chapter 2 / The MacTCP Driver à :ÃÛ ˇ
l ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - ƒ +rIImplementation notes , Times
° d ONLN d 8 Æ CÈ +ZDThis section describes internal algorithms and decisions made by the ° d ONLN d Z F Æ Q ˜ *MacTCP driver.
° d ONLN d i a Æ nN * Fragmentation and reassembly
° d ONLN d Ü y Æ Ñ *NThe Internet Protocol (IP) has the ability to fragment a packet so that it can ° d ONLN d ’ á Æ íˇ *Fbe sent across a network with a small maximum transfer unit (MTU). The ° d ONLN d ï Æ †È *Ffragments are reassembled as they arrive at the destination. Since the ° d ONLN dc £ Æ Æ *Happlication developer must select the size of UDP datagrams (unlike TCP, ° d ONLN d¨ ± Æ ºÔ *Dwhich negotiates packet size), you should be aware of implementation ° d ONLN dÒ ø Æ ò *3limitations imposed on the size of these datagrams. ° d ONLN d% ‘ Æ flÛ *DThe MacTCP driver internally allocates a memory buffer in the system ° d ONLN dj ‚ Æ Ì *Iheap to temporarily hold all incoming fragments waiting to be reassembled ° d ONLN d¥ Æ ˚ *Band all outgoing fragments waiting to be sent. The amount of space ° d ONLN d˜ ˛ Æ Á *Ballocated varies depending on whether 1, 2, or 4 megabytes (MB) of ° d ONLN d: Æ *Ememory are installed. The maximum size of the packet being fragmented ° d ONLN dÄ Æ%¯ *Ior reassembled depends solely on the available free space in this buffer. ° d ONLN d ( Æ3 *HBecause the memory pool is shared by all MacTCP users, the allowance for ° d ONLN d6 ÆAÿ *=the maximum size of a UDPWrite packet will vary, depending on ° d ONLN dQD ÆO˜ *Bcompeting demands on the memory pool. A given destination can only ° d ONLN dîR Æ]˙ *Hguarantee the reassembly of a packet that is 576 bytes (including IP and ° d ONLN d›` Æk˛ *HUDP headers); therefore, it is possible to send a packet from the MacTCP ° d ONLN d&n Æy∂ *:driver that cannot be reassembled by the destination host.
° d ONLN daâ Æñ ÿ * Routing
° d ONLN di° ƨ٠*BThe MacTCP driver supports routing through the Routing Information ° d ONLN d¨Ø Æ∫‚ *DProtocol (RIP) and internally listens to RIP broadcasts. Because the ° d ONLN dÒΩ Æ»¸ *JMacTCP driver internally listens to RIP broadcasts, an attempt to create a ° d ONLN d<À Æ÷à *=UDP stream on local port 520 returns a duplicateSocket error. ° d ONLN dz‡ ÆÎ *<A default gateway can be configured using the Control Panel.
+ˆ“Implementation notes
)`9 à pÃ) ˇ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
0 . ° d ONLN d * T Z j +rn3
° d ONLN d A Æ Tm )ZUser Datagram Protocol , Times
° d ONLN d ™ Æ µ˚ *cDThe User Datagram Protocol (UDP) provides a low-overhead transaction ° d ONLN d ^ ∏ Æ √Ì *Dservice to allow upper-layer protocols to send datagrams between one ° d ONLN d £ Δ Æ — *Lanother. UDP is datagram oriented with best-effort delivery, but it does not ° d ONLN d ‘ Æ flÿ *>use acknowledgments to make sure messages are delivered to the ° d ONLN d/ ‚ Æ ÌÍ *Cdestination, does not order incoming messages, and does not provide ° d ONLN ds Æ ˚ *Ifeedback to control the rate at which information flows between machines. ° d ONLN dΩ ÆÚ *ELike the Transmission Control Protocol (TCP), UDP uses port fields to ° d ONLN d Æ Ê *Dspecify the source and destination processes of each transaction. An ° d ONLN dH! Æ,? * optional checksum is also used. à pÃ) ˇ2 ◊# ˇ ˇˇˇˇ # ◊
° d ONLN d ‚ x Ì *ETo send a UDP datagram, you must format a Write Data Structure (WDS), ° d ONLN dI x ˚” *Kwhich has the format shown in Figure 3-1. A WDS specifies a list of buffers ° d ONLN dï ˛ x ˛ * to write in a single operation. ° d ONLN dµ x “ *KThe simplest WDS describes a single buffer and is 8 bytes in length: a word ° d ONLN d! x,∏ *Elength, a long pointer, followed by a terminating word of 0. The most ° d ONLN dG/ x:‘ *Gcomplex WDS that can be used to send a UDP datagram describes 6 buffers ° d ONLN dè= xH Ï *and is 38 bytes in length.
° ¿ 0 i ° ¿ ° ¿ 0 J ° ¿ ° ¿ 0 j ° ¿ ° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿ [ ° ¿ ]0 d ° ¿
° ¿ %AI3_Note:
° ¿ 0 D
° ¿ -96.453 37.177 m
° ¿ -0.453 37.177 L
° ¿ -0.453 177.177 L
° ¿ -96.453 177.177 L
° ¿ -96.453 37.177 L
° ¿ b
° ¿ 1 g
° ¿ -98.453 39.177 m
° ¿ -2.453 39.177 L
° ¿ -2.453 179.177 L
° ¿ -98.453 179.177 L
° ¿ -98.453 39.177 L
° ¿ b
° ¿ u
° ¿ -98.453 53.927 m
° ¿ -2.453 53.927 l
° ¿ S
° ¿ U
° ¿ u
° ¿ u
° ¿ 0 O
° ¿ 1 g
° ¿ 2 w ° ¿
° ¿ 4.453 105.978 m
° ¿ 4.453 127.228 L
° ¿ -7.797 127.228 L
° ¿ -7.797 105.978 L
° ¿ 4.453 105.978 L
° ¿ f
° ¿ -1.672 116.603 m
° ¿ F
° ¿ U
° ¿ u
° ¿ 0 g
° ¿ 0.25 w ° ¿
° ¿ -3.077 122.045 m
° ¿ /-2.838 121.199 -1.959 120.708 -1.113 120.947 c
° ¿ .-0.268 121.186 0.224 122.066 -0.016 122.911 c
° ¿ .-0.255 123.757 -1.134 124.248 -1.98 124.009 c
° ¿ --2.825 123.77 -3.317 122.89 -3.077 122.045 c
° ¿ f
° ¿ -1.547 122.478 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -3.077 116.045 m
° ¿ /-2.838 115.199 -1.959 114.708 -1.113 114.947 c
° ¿ .-0.268 115.186 0.224 116.066 -0.016 116.911 c
° ¿ .-0.255 117.757 -1.134 118.248 -1.98 118.009 c
° ¿ --2.825 117.77 -3.317 116.89 -3.077 116.045 c
° ¿ f
° ¿ -1.547 116.478 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -3.077 110.045 m
° ¿ /-2.838 109.199 -1.959 108.708 -1.113 108.947 c
° ¿ .-0.268 109.186 0.224 110.066 -0.016 110.911 c
° ¿ .-0.255 111.757 -1.134 112.248 -1.98 112.009 c
° ¿ --2.825 111.77 -3.317 110.89 -3.077 110.045 c
° ¿ f
° ¿ -1.547 110.478 m
° ¿ F
° ¿ U
° ¿ U
° ¿ u
° ¿ u
° ¿ 1 g
° ¿ 2 w ° ¿
° ¿ -92.547 105.978 m
° ¿ -92.547 127.228 L
° ¿ -104.797 127.228 L
° ¿ -104.797 105.978 L
° ¿ -92.547 105.978 L
° ¿ f
° ¿ -98.672 116.603 m
° ¿ F
° ¿ U
° ¿ u
° ¿ 0 g
° ¿ 0.25 w ° ¿
° ¿ -100.077 122.045 m
° ¿ 2-99.838 121.199 -98.959 120.708 -98.113 120.947 c
° ¿ 2-97.268 121.186 -96.776 122.066 -97.016 122.911 c
° ¿ 1-97.255 123.757 -98.134 124.248 -98.98 124.009 c
° ¿ 2-99.825 123.77 -100.317 122.89 -100.077 122.045 c
° ¿ f
° ¿ -98.547 122.478 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -100.077 116.045 m
° ¿ 2-99.838 115.199 -98.959 114.708 -98.113 114.947 c
° ¿ 2-97.268 115.186 -96.776 116.066 -97.016 116.911 c
° ¿ 1-97.255 117.757 -98.134 118.248 -98.98 118.009 c
° ¿ 2-99.825 117.77 -100.317 116.89 -100.077 116.045 c
° ¿ f
° ¿ -98.547 116.478 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -100.077 110.045 m
° ¿ 2-99.838 109.199 -98.959 108.708 -98.113 108.947 c
° ¿ 2-97.268 109.186 -96.776 110.066 -97.016 110.911 c
° ¿ 1-97.255 111.757 -98.134 112.248 -98.98 112.009 c
° ¿ 2-99.825 111.77 -100.317 110.89 -100.077 110.045 c
° ¿ f
° ¿ -98.547 110.478 m
° ¿ F
° ¿ U
° ¿ U
° ¿ u
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -98.453 83.427 m
° ¿ -2.453 83.427 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -97.953 98.177 m
° ¿ -1.953 98.177 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -98.453 164.427 m
° ¿ -2.453 164.427 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -98.453 134.927 m
° ¿ -2.453 134.927 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -50 168.75 0 Tp
° ¿ TP
° ¿ -31.5725 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ /_Helvetica-Narrow 9 Tf
° ¿ 0 Ts
° ¿ 100 Tz
° ¿ 0 Tt
° ¿ 0 TA
° ¿ 0 0 5 TC
° ¿ 100 100 200 TW
° ¿ 0 0 0 Ti
° ¿ 1 Ta
° ¿ 0 Tq
° ¿ 28 0 Tl
° ¿ 0 Tc
° ¿ 0 Tw
° ¿ (length of first buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -50 87.75 0 Tp
° ¿ TP
° ¿ -31.3704 0 Td
° ¿ 0 Tr
° ¿ (length of last buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -98.453 179.177 m
° ¿ -93.5 179.177 l
° ¿ S
° ¿ -98.453 171.8203 m
° ¿ -93.5 171.8203 l
° ¿ S
° ¿ -98.453 164.4635 m
° ¿ -93.5 164.4635 l
° ¿ S
° ¿ -98.453 157.1068 m
° ¿ -93.5 157.1068 l
° ¿ S
° ¿ -98.453 149.7501 m
° ¿ -93.5 149.7501 l
° ¿ S
° ¿ u
° ¿ -98.453 149.7501 m
° ¿ -93.5 149.7501 l
° ¿ S
° ¿ -98.453 142.3934 m
° ¿ -93.5 142.3934 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -98.453 98.1799 m
° ¿ -93.5 98.1799 l
° ¿ S
° ¿ -98.453 90.8232 m
° ¿ -93.5 90.8232 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -98.453 90.7501 m
° ¿ -93.5 90.7501 l
° ¿ S
° ¿ -98.453 83.3934 m
° ¿ -93.5 83.3934 l
° ¿ S
° ¿ -98.453 76.0367 m
° ¿ -93.5 76.0367 l
° ¿ S
° ¿ -98.453 61.3232 m
° ¿ -93.5 61.3232 l
° ¿ S
° ¿ -98.453 68.7867 m
° ¿ -93.5 68.7867 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -98.453 61.2501 m
° ¿ -93.5 61.2501 l
° ¿ S
° ¿ -98.453 53.8934 m
° ¿ -93.5 53.8934 l
° ¿ S
° ¿ -98.453 46.5367 m
° ¿ -93.5 46.5367 l
° ¿ S
° ¿ -98.453 39.1799 m
° ¿ -93.5 39.1799 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -50 147.5 0 Tp
° ¿ TP
° ¿ -32.8008 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿
° ¿ (pointer to first buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -50 67.5 0 Tp
° ¿ TP
° ¿ -32.5986 0 Td
° ¿ 0 Tr
° ¿ (pointer to last buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -50 44.5 0 Tp
° ¿ TP
° ¿ -18.6504 0 Td
° ¿ 0 Tr
° ¿ (zero \(word\)) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -7.703 171.8203 m
° ¿ -2.75 171.8203 l
° ¿ S
° ¿ -7.703 157.1068 m
° ¿ -2.75 157.1068 l
° ¿ S
° ¿ -7.703 149.7501 m
° ¿ -2.75 149.7501 l
° ¿ S
° ¿ u
° ¿ -7.703 149.7501 m
° ¿ -2.75 149.7501 l
° ¿ S
° ¿ -7.703 142.3934 m
° ¿ -2.75 142.3934 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -7.703 90.7501 m
° ¿ -2.75 90.7501 l
° ¿ S
° ¿ -7.703 83.3934 m
° ¿ -2.75 83.3934 l
° ¿ S
° ¿ -7.703 76.0367 m
° ¿ -2.75 76.0367 l
° ¿ S
° ¿ -7.703 61.3232 m
° ¿ -2.75 61.3232 l
° ¿ S
° ¿ -7.703 68.7867 m
° ¿ -2.75 68.7867 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -7.703 61.2501 m
° ¿ -2.75 61.2501 l
° ¿ S
° ¿ -7.703 53.8934 m
° ¿ -2.75 53.8934 l
° ¿ S
° ¿ -7.703 46.5367 m
° ¿ -2.75 46.5367 l
° ¿ S
° ¿ -7.703 39.1799 m
° ¿ -2.75 39.1799 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -50 183.25 0 Tp
° ¿ TP
° ¿
-8.8154 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿
° ¿ (8 bits) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ %%PageTrailer
° ¿
%%Trailer
° ¿ +Adobe_IllustratorA_AI3 /terminate get exec
° ¿ )Adobe_typography_AI3 /terminate get exec
° ¿ &Adobe_customcolor /terminate get exec
° ¿ Adobe_cshow /terminate get exec
° ¿ $Adobe_cmykcolor /terminate get exec
° ¿ &Adobe_packedarray /terminate get exec
° ¿ %%EndDocument
† ø ` ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d Æ , +ÃHReceive buffer area , Times
° d ONLN d 7 Æ B *EThe User Datagram Protocol (UDP) does not allocate memory for storing ° d ONLN d Z E Æ P˘ *FUDP stream databases or for buffering received datagrams. Instead, you ° d ONLN d ° S Æ ^ *Emust pass UDP enough memory for these purposes in the UDPCreate call. ° d ONLN d Á a Æ l *This has two advantages: , p AppleIcon p
° d ONLN d u Æ } ≥ *n
° d ONLN d s ª ~ )
FThe buffer memory can be allocated off the application heap instead of ° d ONLN dI Å ª åk *'the system heap, which is very limited. p
° d ONLN dq ï Æ ù ≥ ( ∫ Ãn
° d ONLN ds ì ª û )
DYou have control over the buffering provided by UDP and can allocate ° d ONLN d∏ ° ª ¨Ó *@the appropriate amount of memory for the type of application and ° d ONLN d˘ Ø ª ∫5 *performance level desired. ° d ONLN d ƒ Æ œ ( Î ÃGThis buffer area for incoming datagrams belongs to the MacTCP driver as ° d ONLN d\ “ Æ ›
*Ilong as the UDP stream is open. When UDPRelease is called, this memory is ° d ONLN d¶ ‡ Æ Î‰ *Ereturned to you and you can then reuse it or return it to the system.
° d ONLN dÏ T é (0 r Using UDP
° d ONLN dˆ Æ* +ZITo send or receive UDP datagrams, you must first call UDPCreate to create ° d ONLN d@- Æ8 *Ka UDP stream, creating a port listener for the given UDP port and passing a ° d ONLN då; ÆF *Fmemory block to the UDP driver to use in buffering incoming datagrams. ° d ONLN d”I ÆT *HUDPCreate also registers an asynchronous notification routine (ASR) that ° d ONLN d W Æb¸ *FUDP uses to notify you of asynchronous events associated with this UDP ° d ONLN dce ÆpÕ *9stream. The MacTCP driver can support 63 open UDP streams ° d ONLN dùs Æ~˜ *Esimultaneously. The RIP process always has a stream open on port 520. ° d ONLN d„à Æì *GTo receive a UDP datagram, call UDPRead. Then, when you finish with the ° d ONLN d+ñ Æ°Ú *Ebuffer that holds the received datagram, call UDPBfrReturn. To send a ° d ONLN dq§ ÆØÚ *CUDP datagram, call UDPWrite. When you finish using a UDP port, call ° d ONLN dµ≤ ÆΩZ *#UDPRelease to close the UDP stream. ° d ONLN dŸƒ Æœ « *Note: ° d ONLN dfiƒ «œÒ )A Use of link-level packets larger than the maximum transfer unit ° d ONLN d “ Æ›Ò (˘ ÃD(MTU) on LocalTalk networks is not advised because there are several ° d ONLN de‡ ÆÎÈ *Bproblems with these packets on Datagram Delivery Protocol-Internet ° d ONLN d®Ó Æ˘¸ *DProtocol (DDP-IP) gateways. The packet MTU size should be negotiated ° d ONLN d̸ Æ$ *by upper-layer protocols. (Ÿ„ Using UDP
);13 à pÃ) ˇò ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - d +<I UDP routines , Times
° d ONLN d
8 x Cø +ZHThis section describes calls to the UDP driver. Table 3-1 lists each UDP ° d ONLN d V F x Q Á *routine and its function.
° d ONLN d p b x m ú * Table 3-1 ° d ONLN d y b ú m “ )$ UDP routines
° d ONLN d à v x ~ ë ( õ ñRoutine ° d ONLN d ê v “ ~ Ó )ZFunction è î èÛ ° î °Û
° d ONLN d ô à x ì § ( Ø ñ UDPCreate ° d ONLN d £ à “ ì )ZOpens a UDP stream ° d ONLN d ∂ ó x ¢ ù ( æ ñUDPRead ° d ONLN d æ ó “ ¢É )Z-Retrieves a datagram received on a UDP stream ° d ONLN d Ï ¶ x ± ≤ ( Õ ñ UDPBfrReturn ° d ONLN d ˘ ¶ “ ±r )Z*Returns a receive buffer to the UDP driver ° d ONLN d$ µ x ¿ † ( ‹ ñUDPWrite ° d ONLN d- µ “ ¿U )Z Sends a datagram on a UDP stream ° d ONLN dN ƒ x œ ¶ ( Î ñ
UDPRelease ° d ONLN dY ƒ “ œ )ZCloses a UDP stream ° d ONLN dm ” x fi ú ( ˙ ñUDPMTU ° d ONLN dt ” “ fi“ )ZCReturns the maximum size of UDP data that can be sent in a datagram ° d ONLN d∏ fl “ Í/ * without IP fragmentation ° d ONLN d— Ó x ˘ À ( ñUDP Multiport Create ° d ONLN dÊ Ó “ ˘û )Z6Opens UDP connections on a consecutive series of ports ° d ONLN d ˝ x ƒ ($ ñUDP Multiport Send ° d ONLN d0 ˝ “f )Z&Sends a datagram from a specified port ° d ONLN dX x Õ (3 ñUDP Multiport Receive ° d ONLN dn “à )ZAReceives data from a port that was created with the UDP Multiport ° d ONLN d∞ “# * Create command K îKÛ (Ÿ <14
ß Æ≤ *Kthe routine is 0, you are not notified of asynchronous events. See the next ° d ONLN dVµ Æ¿Œ *:section, “UDP Asynchronous Notification Routine,” for more ° d ONLN dë√ ÆŒ Ë * information. ° d ONLN dûÿ Æ„´ *9If the local port is 0, UDP assigns an unused local port. ° d ONLN dÿÌ Æ¯˝ *IThe user data pointer is returned in all ASRs for the created UDP stream. ° d ONLN d" U
é () s Result codes ° d ONLN d/ Æ
… )YnoErr ° d ONLN d55
[ )áno error ° d ONLN d> Æ
(; ÃstreamAlreadyOpen ° d ONLN dP5 ¸ )á,an open stream is already using this receive ° d ONLN d}"5-h * buffer area ° d ONLN dâ4 Æ? Ó ([ Ã
invalidLength ° d ONLN dó45?” )á$the receive buffer area is too small ° d ONLN dºF ÆQ Î (m Ã
invalidBufPtr ° d ONLN d F5Q” )á$the receive buffer area pointer is 0 ° d ONLN dÔX Æc ˜ ( ÃduplicateSocket ° d ONLN dˇX5cÚ )á*an open stream is already using this local ° d ONLN d*f5qa *UDP port ° d ONLN d3x ÆÉ (ü ÃinsufficientResources ° d ONLN dIx5Éœ )á 64 UDP streams are already open +Ü: UDP routines
)E15 Ã pÃ) ˇ
‹ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d x ," +ñH%UDP asynchronous notification routine , Times
° d ONLN d & 6 x A¬ *FThe asynchronous notification routine (ASR), which was registered with ° d ONLN d m D x Oì *<UDP in the UDPCreate call, is called by UDP to notify you of ° d ONLN d ™ R x ]~ *8asynchronous events relevant to a particular UDP stream. ° d ONLN d „ g x r” *OSince this routine is called from the interrupt level, you must not allocate or ° d ONLN d3 u x Ä√ *Freturn memory to the system. Also, you are not allowed to make further ° d ONLN dz É x é… *Fsynchronous MacTCP calls from an ASR. The values of all registers must ° d ONLN d¡ ë x ú] *.be preserved except registers A0–A2 and D0–D2. ° d ONLN d ≠ x ∏= * +The C description of the ASR is as follows: ,
Courier
° d ONLN d æ x *pascal void UDPNotifyProc ( ° d ONLN d9 Ã ñ ÿ + StreamPtr udpStream, ° d ONLN dO ⁄ ñ Ê, *unsigned short eventCode, ° d ONLN dj Ë ñ Ù ˆ *Ptr userDataPtr, ° d ONLN d| ˆ ñ> * struct ICMPReport *icmpMsg); ° d ONLN dô x ¥ (3 ñ
NotifyProc
° d ONLN d£ ¥“ )<@ is passed to the UDPCreate call for use on notification of data ° d ONLN d‰ x%Δ (A ñIarrival and ICMP message reception. If this method of notification is not ° d ONLN d.( x3æ *Fdesired, no procedure should be passed to the UDPCreate call. (Pass an ° d ONLN du6 xAΩ *EASR pointer value of NIL.) Asynchronous notification is used with the ° d ONLN dªD xO‘ *DUDPRead command only. All other commands complete in a finite amount ° d ONLN d R x]6 *(of time and can be called synchronously. ° d ONLN d)g xr” *KAt entry, A0 contains the stream pointer, A1 contains a pointer to the ICMP ° d ONLN duu xÄ… *Jreport structure if the event code in D0 is ICMP received, A2 contains the ° d ONLN d¿É xé» *Luser data pointer, A5 is already set up to point to application globals, and ° d ONLN d
ë xú *!D0 (word) contains an event code. ° d ONLN d/¶ ± U (Õ < Event codes ° d ONLN d;¶ x± √ )ZUDPDataArrival ° d ONLN dJ¶ ˇ±√ )á)a UDP datagram has arrived on this stream ° d ONLN dv¥ ˇøà *'but no UDPRead commands are outstanding ° d ONLN dûΔ x— “ (Ì ñUDPICMPReceived ° d ONLN dÆΔ ˇ—¬ )á)an ICMP has been received on this stream; ° d ONLN dÿ‘ ˇfl´ *%register A1 points to the ICMP report ° d ONLN d˛È xÙ” ( ñIAn ICMP message reports an error in the processing of a datagram that was ° d ONLN dH˜ xŒ *Hsent on a UDP stream. When an ICMP message is received, a data structure ° d ONLN dë x¬ *His passed up by UDP to the client to describe the received message. This ° d ONLN d⁄ x ö *@data structure, called an ICMP report, has the following format: ° d ONLN d( x3 ~ *0 ° d ONLN d ( •3 ∫ )-long ° d ONLN d"( “3 )-stream pointer ° d ONLN d1= xH ~ (d ñ4 ° d ONLN d3= •H ∫ )-long ° d ONLN d8= “HH )-local IP address of stream ° d ONLN dSR x] ~ (y ñ8 ° d ONLN dUR •] º )-word ° d ONLN dZR “]E )-local UDP port of stream ° d ONLN dsg xr Ñ (é ñ10 ° d ONLN dvg •r ∫ )-long ° d ONLN d{g “r√ )-4remote IP address (destination of original datagram) ° d ONLN d∞| xá Ñ (£ ñ14 ° d ONLN d≥| •á º )-word ° d ONLN d∏| “á! )-remote UDP port
(Ÿ <16
)"Chapter 3 / User Datagram Protocol à :ÃÛ ˇ p ◊# ˇ ˇˇˇˇ # ◊
time exceeded ° d ONLN d9 Æ ¥ (6 Ã7 ° d ONLN d; €3 )-parameter problem ° d ONLN dM$ Æ/ ¥ (K Ã8 ° d ONLN dO$ €/I )-missing required option ° d ONLN dg@ ÆKI (g Ã!Codes 0–3 are defined as follows: , p AppleIcon p
° d ONLN dâT Æ\ ≥ *n
° d ONLN dãR ª]„ )
ANet unreachable indicates that, according to the information in a ° d ONLN dÕ` ªk *Kgateway routing table, the network specified in the IP destination field of ° d ONLN dn ªyO * a UDP datagram is unreachable. p
° d ONLN d8Ç Æä ≥ (ß Ãn
° d ONLN d:Ä ªãÏ )
BHost unreachable indicates that a gateway determined that the host ° d ONLN d}é ªôˇ *Gspecified in the IP destination field of a UDP datagram is unreachable. p
° d ONLN dΔ¢ Æ™ ≥ (« Ãn
° d ONLN d»† ª´ )
GProtocol unreachable indicates that a UDP datagram was delivered to the ° d ONLN dÆ ªπÍ *Adestination host, but UDP was not ready to receive any datagrams. p
° d ONLN dR¬ Æ ≥ (Á Ãn
° d ONLN dT¿ ªÀÙ )
CPort unreachable indicates that a UDP datagram was delivered to the ° d ONLN dòŒ ªŸ *Jdestination host, but no UDP client was listening on that particular port. ° d ONLN d‰Í Æı ( ÃEThese ICMP messages may be received occasionally when the topology of ° d ONLN d*¯ Æ *Ithe internet changes. A single destination unreachable message should not ° d ONLN dt Æ *Gbe taken too seriously; however, if several successive UDPSend commands ° d ONLN dº Æ *Meach result in an ICMP report indicating that the destination is unreachable, ° d ONLN d
" Æ- *Jthe UDP client should assume that the remote host has either crashed or is ° d ONLN dU0 Æ; *no longer accessible. ° d ONLN dkE ÆPÎ *CThe remaining codes (4–8) indicate problems in the format of the IP ° d ONLN dØS Æ^˝ *Dheader on a UDP datagram. They are informational only. Since the UDP ° d ONLN dÙa Æl› *Dclient has no access to the IP header, you cannot correct the error. , N Helvetica Narrow (ŸŸ UDP routines
)E17 à pÃ) ˇ“ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - S +<IUDPRead , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d " 8 ˛ CY ),csCode = UDPRead ° d ONLN d 3 I x U É ( q ñÆ ° d ONLN d 5 J • U ± )-28 ° d ONLN d 8 J “ U Á )-long ° d ONLN d = J ˇ UA )-stream pointer ° d ONLN d L [ x g É ( É ñÆ ° d ONLN d N \ • g ± )-32 ° d ONLN d Q \ “ g È )-word ° d ONLN d V \ ˇ g° )- command timeout value in seconds ° d ONLN d x j ˇ u; *(0 = infinite) ° d ONLN d á { x á É ( £ ñ¨ ° d ONLN d â | • á ± )-34 ° d ONLN d å | “ á Á )-long ° d ONLN d ë | ˇ áQ )-remote IP address ° d ONLN d £ ç x ô É ( µ ñ¨ ° d ONLN d • é • ô ± )-38 ° d ONLN d ® é “ ô È )-word ° d ONLN d ≠ é ˇ ôN )-remote UDP port ° d ONLN d Ω ü x ´ É ( « ñ¨ ° d ONLN d ø † • ´ ± )-40 ° d ONLN d ¬ † “ ´ Á )-long ° d ONLN d « † ˇ ´[ )-pointer to UDP data ° d ONLN d € ± x Ω É ( Ÿ ñ¨ ° d ONLN d › ≤ • Ω ± )-44 ° d ONLN d ‡ ≤ “ Ω È )-word ° d ONLN d  ≤ ˇ ΩX )-length of UDP data ° d ONLN d ¯ √ x œ É ( Î ñÆ ° d ONLN d ˙ ƒ • œ ± )-46 ° d ONLN d ˝ ƒ “ œ È )-word ° d ONLN d ƒ ˇ œs )-reserved; must be set to 0 ° d ONLN d ’ x · É ( ˝ ñÆ ° d ONLN d ÷ • · ± )-48 ° d ONLN d" ÷ “ · Á )-long ° d ONLN d' ÷ ˇ ·L )-user data pointer ° d ONLN d9 Î x ˆΔ ( ñEUDPRead retrieves a datagram that has been received on the UDP stream ° d ONLN d ˘ x¬ *Ddefined by the stream pointer. Some number of datagrams are buffered ° d ONLN dƒ xœ *Dinternally within UDP even when no UDPRead commands are outstanding, ° d ONLN d x ‘ *Jso it is not necessary to keep a UDPRead command outstanding at all times. ° d ONLN dT# x.Δ *DThe exact number of datagrams that can be buffered within the MacTCP ° d ONLN dô1 x<Δ *Hdriver depends on the size of the receive buffer area given to MacTCP in ° d ONLN d‚? xJs *6the UDPCreate call and the size of datagrams received. ° d ONLN dT x_¥ *>If a UDP datagram arrives on an open UDP stream and no UDPRead ° d ONLN dXb xm¬ *Hcommands are outstanding, you are given a data arrival notification as a ° d ONLN d°p x{¡ *Bhint that a UDPRead command should be issued. See the section “UDP ° d ONLN d‰~ x⥠*CAsynchronous Notification Routine” earlier in this chapter for more ° d ONLN d(å xó ≤ * information. ° d ONLN d5° x¨∂ *BThe command timeout period is specified in seconds. If no datagram ° d ONLN dxØ x∫ *Farrives within the timeout period, the UDPRead command is completed in ° d ONLN døΩ x»Œ *Ferror. The minimum allowed value for the command timeout is 2 seconds. ° d ONLN dÀ x÷à *CA zero command timeout means infinite; the UDPRead command will not ° d ONLN dJŸ x‰( *&be completed until a datagram arrives. ° d ONLN dqÓ x˘π *CThe remote IP address and remote UDP port specify the source of the ° d ONLN dµ¸ x ¶ * datagram. ° d ONLN dø x – *HUDPRead can return successfully even though the length of UDP data is 0. ° d ONLN d x*— *JThis happens when a UDP packet arrives that has the passed-in value of the ° d ONLN dS- x8¬ *DUDP stream’s local UDP port, but contains no data. Since the UDPSend ° d ONLN dò; xF∏ *>command permits sending zero-length UDP datagrams, the UDPRead ° d ONLN d◊I xTì *8command must pass up zero-length datagrams for symmetry. ° d ONLN d^ xiœ *FFor every UDPRead command that is completed successfully and returns a ° d ONLN dWl xw” *Gnonzero amount of data, you must call UDPBfrReturn with the same stream ° d ONLN düz xÖ∑ *Epointer and UDP data pointer, to return the receive buffer to the UDP ° d ONLN dÂà xì ¬ *driver for reuse.
! Æ , … )ZnoErr ° d ONLN d !5 ,[ )áno error ° d ONLN d 3 Æ > ˙ ( Z ÃinvalidStreamPtr ° d ONLN d - 35 >fl )á$the specified UDP stream is not open ° d ONLN d R E Æ P ( l ÃcommandTimeout ° d ONLN d a E5 P˜ )á+no data arrived within the specified period ° d ONLN d é W Æ b ( ~ ÃconnectionTerminated ° d ONLN d £ W5 b )á#a UDPRelease command closed the UDP , N Helvetica Narrow
° d ONLN d » } T ã ° ( ß r UDPBfrReturn
° d ONLN d ’ ñ T ° † *Parameter block , Symbol ° d ONLN d  ï Æ ° π )ZÆ ° d ONLN d Á ñ € ° Á )-26 ° d ONLN d Í ñ ° )-word ° d ONLN d Ô ñ5 °ß )-csCode = UDPBfrReturn ° d ONLN d ß Æ ≥ π ( œ ÃÆ ° d ONLN d ® € ≥ Á )-28 ° d ONLN d
® ≥ )-long ° d ONLN d ®5 ≥w )-stream pointer ° d ONLN d π Æ ≈ π ( · ÃÆ ° d ONLN d ∫ € ≈ Á )-40 ° d ONLN d# ∫ ≈ )-long ° d ONLN d( ∫5 ≈ë )-pointer to UDP data ° d ONLN d< À Æ ◊ π ( Û ÃÆ ° d ONLN d> à € ◊ Á )-48 ° d ONLN dA à ◊ )-long ° d ONLN dF Ã5 ◊Ç )-user data pointer ° d ONLN dX · Æ Ïı ( ÃEUDPBfrReturn returns a receive buffer to the UDP driver that had been ° d ONLN dû Ô Æ ˙„ *Bpassed to you because of a successful UDPRead call that returned a ° d ONLN d· ˝ Æ *nonzero amount of data. ° d ONLN d˘ T ç (9 r Result codes ° d ONLN d Æ … )ZnoErr ° d ONLN d 5 [ )áno error ° d ONLN d$ Æ/ ˙ (K ÃinvalidStreamPtr ° d ONLN d&$5/fl )á$the specified UDP stream is not open ° d ONLN dK6 ÆA Î (] Ã
invalidBufPtr ° d ONLN dY65A )á,the user does not own the UDP receive buffer (ŸŸ UDP routines
)E19 à pÃ) ˇ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - T +<IUDPWrite , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d # 8 ˇ C[ )-csCode = UDPWrite ° d ONLN d 5 I x U É ( q ñÆ ° d ONLN d 7 J • U ± )-28 ° d ONLN d : J “ U Á )-long ° d ONLN d ? J ˇ UA )-stream pointer ° d ONLN d N [ x g É ( É ñÆ ° d ONLN d P \ • g ± )-34 ° d ONLN d S \ “ g Á )-long ° d ONLN d X \ ˇ gQ )-remote IP address ° d ONLN d j m x y É ( ï ñÆ ° d ONLN d l n • y ± )-38 ° d ONLN d o n “ y È )-word ° d ONLN d t n ˇ yN )-remote UDP port ° d ONLN d Ñ x ã É ( ß ñÆ ° d ONLN d Ü Ä • ã ± )-40 ° d ONLN d â Ä “ ã Á )-long ° d ONLN d é Ä ˇ ãF )-pointer to WDS ° d ONLN d ù ë x ù É ( π ñÆ ° d ONLN d ü í • ù ± )-44 ° d ONLN d ¢ í “ ù Ê )-byte ° d ONLN d ß í ˇ ùB )-
checksum flag ° d ONLN d µ £ x Ø É ( À ñÆ ° d ONLN d ∑ § • Ø ± )-46 ° d ONLN d ∫ § “ Ø È )-word ° d ONLN d ø § ˇ ØÅ )- reserved; must be set to zero ° d ONLN d › µ x ¡ É ( › ñÆ ° d ONLN d fl ∂ • ¡ ± )-48 ° d ONLN d ‚ ∂ “ ¡ Á )-long ° d ONLN d Á ∂ ˇ ¡L )-user data pointer ° d ONLN d ˘ À x ÷L ( Ú ñ*UDPWrite sends a datagram on a UDP stream. ° d ONLN d% ‡ x ε *DThe datagram’s destination is specified by the remote IP address and ° d ONLN dj Ó x ˘Ã *Eremote UDP parameter ports. The buffers described by the WDS must not ° d ONLN d∞ ¸ x‘ *Fbe modified or relocated until the command has been completed. The WDS ° d ONLN d˜
invalidWDS ° d ONLN d÷ˆ ˇ— )á*too many buffers are in WDS or WDS pointer ° d ONLN d ˇ *is NIL ° d ONLN d x! ∏ (= ñ
invalidLength ° d ONLN d ˇ!º )á)the total amount of data described by the ° d ONLN dA$ x/ í (K ñWDS ° d ONLN dF$ ˇ/á )á was greater than 65,535 bytes ° d ONLN dd6 xA ⁄ (] ñinsufficientResources ° d ONLN dz6 ˇA« )á*too many datagrams are outstanding in the ° d ONLN d•D ˇOC *transmit queue ° d ONLN d¥V xa À (} ñipNoFragMemErr ° d ONLN d√V ˇa– )á.insufficient internal memory was available to ° d ONLN dÚd ˇo[ *fragment the packet ° d ONLN dv xÅ ´ (ù ñ
ipRouteErr ° d ONLN dv ˇÅÀ )á,unable to send the packet to an off-network ° d ONLN d>Ñ ˇèø *)destination because all gateways are down
(Ÿ <20
)"Chapter 3 / User Datagram Protocol à :ÃÛ ˇ h ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - ó +rI
UDPRelease , Times
° d ONLN d 8 T C † *Parameter block , Symbol ° d ONLN d 7 Æ C π )ZÆ ° d ONLN d 8 € C Á )-26 ° d ONLN d 8 C )-word ° d ONLN d % 85 Cõ )-csCode = UDPRelease ° d ONLN d 9 I Æ U π ( q ÃÆ ° d ONLN d ; J € U Á )-28 ° d ONLN d > J U )-long ° d ONLN d C J5 Uw )-stream pointer ° d ONLN d R [ Æ g π ( É Ã¨ ° d ONLN d T \ € g Á )-32 ° d ONLN d W \ g )-long ° d ONLN d \ \5 gª )- pointer to receive buffer area ° d ONLN d { m Æ y π ( ï è ° d ONLN d } n € y Á )-36 ° d ONLN d Ä n y )-long ° d ONLN d Ö n5 y∏ )- length of receive buffer area ° d ONLN d £ Æ ã π ( ß ÃÆ ° d ONLN d • Ä € ã Á )-46 ° d ONLN d ® Ä ã )-long ° d ONLN d ≠ Ä5 ãÇ )-user data pointer ° d ONLN d ø ï Æ †Ò ( º Ã@UDPRelease closes a UDP stream. Any outstanding commands on that ° d ONLN d £ Æ Æ˙ *Hstream are terminated with an error. The ownership of the receive buffer ° d ONLN dI ± Æ º™ *6area used to create the UDP stream passes back to you. ° d ONLN dÄ Δ Æ —› *@Before UDPRelease is called, you must make sure that all pending ° d ONLN d¡ ‘ Æ flÛ *AUDPWrite commands have been completed. There is no way to abort a ° d ONLN d ‚ Æ ÌF * UDPWrite command in progress. ° d ONLN d! Ù Æ ˇ « *Note: ° d ONLN d& Ù « ˇ˙ )B UDP Release must be called to release memory that is held by the ° d ONLN di Æ
º () Ã;driver. Failure to do so may produce unpredictable results. ° d ONLN d¶ T" ç (> r Result codes ° d ONLN d≥ Æ" … )ZnoErr ° d ONLN dπ5"[ )áno error ° d ONLN d¬) Æ4 ˙ (P ÃinvalidStreamPtr ° d ONLN d”)54fl )á$the specified UDP stream is not open
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d % 7 x C É )ZÆ ° d ONLN d ' 8 • C ± )-26 ° d ONLN d * 8 “ C È )-word ° d ONLN d / 8 ˇ Cy )-csCode = UDPMultiCreate ° d ONLN d G I x U É ( q ñ¨ ° d ONLN d I J • U ± )-28 ° d ONLN d L J “ U Á )-long ° d ONLN d Q J ˇ UA )-stream pointer ° d ONLN d ` [ x g É ( É ñÆ ° d ONLN d b \ • g ± )-32 ° d ONLN d e \ “ g Á )-long ° d ONLN d j \ ˇ gÖ )- pointer to receive buffer area ° d ONLN d â m x y É ( ï ñÆ ° d ONLN d ã n • y ± )-36 ° d ONLN d é n “ y Á )-long ° d ONLN d ì n ˇ yÇ )- length of receive buffer area ° d ONLN d ± x ã É ( ß ñÆ ° d ONLN d ≥ Ä • ã ± )-40 ° d ONLN d ∂ Ä “ ã Á )-long ° d ONLN d ª Ä ˇ ㌠)--pointer to asynchronous notification routine ° d ONLN d Î é ˇ ô *(ASR) ° d ONLN d Ò ü x ´ É ( « ñÆ ° d ONLN d Û † • ´ ± )-44 ° d ONLN d ˆ † “ ´ È )-word ° d ONLN d ˚ † ˇ ´P )-starting UDP port ° d ONLN d
± x Ω É ( Ÿ ñÆ ° d ONLN d ≤ • Ω ± )-46 ° d ONLN d ≤ “ Ω Á )-long ° d ONLN d ≤ ˇ ΩL )-user data pointer ° d ONLN d) √ x œ É ( Î ñÆ ° d ONLN d+ ƒ • œ ± )-50 ° d ONLN d. ƒ “ œ È )-word ° d ONLN d3 ƒ ˇ œ5 )- ending port ° d ONLN d? Ÿ x ‰Δ ( ñEUDP Multiport Create opens UDP connections on a consecutive series of ° d ONLN dÖ Á x Ú‘ *Oports. This routine is similar to UDPCreate except that it takes a starting and ° d ONLN d’ ı x ø *Gending port instead of a single UDP port. The starting port must not be ° d ONLN d xΔ *Jzero. The connection is established on a range of ports, from the starting ° d ONLN dh x ” *Jport to the ending port, inclusive. The UDP Multiport Send routine must be ° d ONLN d≥ x*¥ *Dused with this type of connection stream (see the next section, “UDP ° d ONLN d¯- x8Œ *IMultiport Send”). Reading datagrams from this type of stream is identical ° d ONLN dB; xFÀ *Fto UDPRead, except that the receiving port may change from datagram to ° d ONLN dâI xT ¶ * datagram. ° d ONLN dì^ i W (Ö < Result codes ° d ONLN d†^ xi ì )ZnoErr ° d ONLN d¶^ ˇi% )áno error ° d ONLN dØp x{ ‘ (ó ñstreamAlreadyOpen ° d ONLN d¡p ˇ{Δ )á,an open stream is already using this receive ° d ONLN dÓ~ ˇâ2 * buffer area ° d ONLN d˙ê xõ ∏ (∑ ñ
invalidLength ° d ONLN d ê ˇõù )á$the receive buffer area is too small ° d ONLN d.¢ x≠ µ (… ñ
invalidBufPtr ° d ONLN d=¢ ˇ≠ù )á$the receive buffer area pointer is 0 ° d ONLN db¥ xø ¡ (€ ñduplicateSocket ° d ONLN ds¥ ˇøº )á*an open stream is already using this local ° d ONLN dû¬ ˇÕ+ *UDP port ° d ONLN dß‘ xfl ⁄ (˚ ñinsufficientResources ° d ONLN dΩ‘ ˇflô )á 64 UDP streams are already open
checksum flag ° d ONLN d √ £ Æ Ø π ( À ÃÆ ° d ONLN d ≈ § € Ø Á )-46 ° d ONLN d » § Ø )-word ° d ONLN d Õ §5 Ø[ )-reserved ° d ONLN d ÷ µ Æ ¡ π ( › ÃÆ ° d ONLN d ÿ ∂ € ¡ Á )-48 ° d ONLN d € ∂ ¡ )-long ° d ONLN d ‡ ∂5 ¡Ç )-user data pointer ° d ONLN d Ú « Æ ” π ( Ô ÃÆ ° d ONLN d Ù » € ” Á )-52 ° d ONLN d ˜ » ” )-word ° d ONLN d ¸ »5 ”a )-
local port ° d ONLN d › Æ Ë› ( Ã?UDP Multiport Send sends a datagram from a specified port. (See ° d ONLN dG Î Æ ˆ Û * “UDPWrite.”) ° d ONLN dT T ç (' r Result codes ° d ONLN da Æ … )ZnoErr ° d ONLN dg 5 [ )áno error ° d ONLN dp Æ ˙ (9 ÃinvalidStreamPtr ° d ONLN dÇ5 fl )á$the specified UDP stream is not open ° d ONLN dß$ Æ/ ‰ (K Ã
invalidWDS ° d ONLN d≥$5/ )á*too many buffers are in WDS or WDS pointer ° d ONLN dfi25=R *is NIL ° d ONLN dÂD ÆO Ó (k Ã
invalidLength ° d ONLN dÙD5OÚ )á)the total amount of data described by the ° d ONLN d R5]◊ *!WDS was greater than 65,535 bytes ° d ONLN d@d Æo (ã ÃinsufficientResources ° d ONLN dVd5o˙ )á)too many datagrams are outstanding in the ° d ONLN dÄr5}y *transmit queue ° d ONLN dèÑ Æè (´ ÃipNoFragMemErr ° d ONLN düÑ5è˙ )á,insufficient internal memory is available to ° d ONLN dÃí5ùë *fragment the packet ° d ONLN d‡§ ÆØ · (À Ã
ipRouteErr ° d ONLN dϧ5Ø˛ )á+unable to send the packet to an off-network ° d ONLN d≤5Ωı *)destination because all gateways are down (ŸŸ UDP routines
)D23 Ã pÃ) ˇ
Æ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - ï +<IUDP Multiport Receive , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d & 7 x C É )ZÆ ° d ONLN d ( 8 • C ± )-26 ° d ONLN d + 8 “ C È )-word ° d ONLN d 0 8 ˇ Cs )-csCode = UDPMultiRead ° d ONLN d F I x U É ( q ñÆ ° d ONLN d H J • U ± )-28 ° d ONLN d K J “ U Á )-long ° d ONLN d P J ˇ UA )-stream pointer ° d ONLN d _ [ x g É ( É ñÆ ° d ONLN d a \ • g ± )-32 ° d ONLN d d \ “ g È )-word ° d ONLN d i \ ˇ g° )- command timeout value in seconds ° d ONLN d ã j ˇ u; *(0 = infinite) ° d ONLN d ö { x á É ( £ ñ¨ ° d ONLN d ú | • á ± )-34 ° d ONLN d ü | “ á Á )-long ° d ONLN d § | ˇ áQ )-remote IP address ° d ONLN d ∂ ç x ô É ( µ ñ¨ ° d ONLN d ∏ é • ô ± )-38 ° d ONLN d ª é “ ô È )-word ° d ONLN d ¿ é ˇ ôN )-remote UDP port ° d ONLN d – ü x ´ É ( « ñ¨ ° d ONLN d “ † • ´ ± )-40 ° d ONLN d ’ † “ ´ Á )-long ° d ONLN d ⁄ † ˇ ´[ )-pointer to UDP data ° d ONLN d Ó ± x Ω É ( Ÿ ñ¨ ° d ONLN d ≤ • Ω ± )-44 ° d ONLN d Û ≤ “ Ω È )-word ° d ONLN d ¯ ≤ ˇ ΩX )-length of UDP data ° d ONLN d √ x œ É ( Î ñÆ ° d ONLN d
° d ONLN d≠™ Ƶ˘ * DThe following parameter block is used for UDPCreate, UDPMultiCreate, ° d ONLN dÚ∏ Æ√ *and UDPRelease calls:
° d ONLN d… Æ’V * typedef struct UDPCreatePB { " ° ∂ ° ∂ ° ∂ ° d ONLN d&◊ Ä ‰ + Ptr ° d ONLN d+◊5„e )ircvBuff; ° d ONLN d5 ÃÒ (
Í
unsigned long ° d ONLN dCÂ5Òw )i rcvBuffLen; ° d ONLN dPÛ Ãˇ ( Í
UDPNotifyProc ° d ONLN d^Û5ˇw )i notifyProc; ° d ONLN dk Ã
() Íunsigned short ° d ONLN dz5
q )i
localPort; ° d ONLN dÜ Ã fi (7 ÍPtr ° d ONLN dä5} )i userDataPtr; ° d ONLN dò Ã) ¸ (E Íudp_port ° d ONLN d° 5)w )i endingPort; ° d ONLN d≠+ Æ7 (S Ã} UDPCreatePB;
° d ONLN dºAãL +› Continued on following page , p AppleIcon p ° d ONLN dÿ@K
)x. (Ÿï C parameter-block definitions
)à25 à pÃ) ˇf ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x , +ñHtypedef struct UDPSendPB { ° d ONLN d . ñ : Í + unsigned short ° d ONLN d + . ˇ :5 )i reserved; ° d ONLN d 6 < ñ H ¿ ( d ¥ip_addr ° d ONLN d > < ˇ HA )i remoteHost; ° d ONLN d K J ñ V Δ ( r ¥udp_port ° d ONLN d T J ˇ VA )i remotePort; ° d ONLN d a X ñ d ® ( Ä ¥Ptr ° d ONLN d e X ˇ d) )iwdsPtr; ° d ONLN d n f ñ r ¿ ( é ¥Boolean ° d ONLN d v f ˇ r5 )i checkSum; ° d ONLN d Å t ñ Ä Í ( ú ¥unsigned short ° d ONLN d ê t ˇ ÄA )i sendLength; ° d ONLN d ù Ç ñ é ® ( ™ ¥Ptr ° d ONLN d ° Ç ˇ éG )i userDataPtr; ° d ONLN d Ø ê ñ ú Δ ( ∏ ¥udp_port ° d ONLN d ∏ ê ˇ ú; )i
localPort; ° d ONLN d √ û x ™ ¿ ( Δ ñ } UDPSendPB; , Times
° d ONLN d – ª x ΔÇ * 7The following parameter block is used with the UDPRead, ° d ONLN d … x ‘_ *+UDPMultiReceive, and UDPBfrReturn commands:
° d ONLN d4 ⁄ x Ê& * typedef struct UDPReceivePB { ° d ONLN dS Ë ñ Ù Í + unsigned short ° d ONLN db Ë, Ù\ )ñtimeOut; ° d ONLN dl ˆ ñ ¿ ( ¥ip_addr ° d ONLN dt ˆ,n )ñ remoteHost; ° d ONLN dÅ ñ Δ (, ¥udp_port ° d ONLN dä,n )ñ remotePort; ° d ONLN dó ñ Æ (: ¥Ptr ° d ONLN dú, \ )ñrcvBuff; ° d ONLN d¶ ñ, Í (H ¥unsigned short ° d ONLN dµ ,,n )ñ rcvBuffLen; ° d ONLN d¬. ñ: Í (V ¥unsigned short ° d ONLN d—.,:å )ñsecondTimeStamp; ° d ONLN d„< ñH ® (d ¥Ptr ° d ONLN dÁ<,Ht )ñ userDataPtr; ° d ONLN dıJ ñV ¿ (r ¥ip_addr ° d ONLN d˝J,Vb )ñ destHost; ° d ONLN dX ñd Δ (Ä ¥udp_port ° d ONLN dX,db )ñ destPort; ° d ONLN df xr “ (é ñ} UDPReceivePB; ° d ONLN d+x xÑ *typedef struct UDPMTUPB { ° d ONLN dFÜ ñí Í + unsigned short ° d ONLN dUÜ,í\ )ñmtuSize; ° d ONLN d_î ñ† ¿ (º ¥ip_addr ° d ONLN dgî,†n )ñ remoteHost; ° d ONLN dt¢ ñÆ ® ( ¥Ptr ° d ONLN dx¢,Æt )ñ userDataPtr; ° d ONLN dÖ∞ xº ∫ (ÿ ñ } UDPMTUPB; , N Helvetica Narrow (Ÿ <26
. ° d ONLN d Æ ,> +ÃHtypedef struct UDPiopb { ° d ONLN d . Ã : ‰ + char ° d ONLN d .b :§ )ñ fill12[12]; ° d ONLN d - < Ã H> ( d ÍUDPIOCompletionProc ° d ONLN d A <b H∞ )ñ
ioCompletion; ° d ONLN d P J à V Í ( r Íshort ° d ONLN d V Jb Vò )ñ ioResult; ° d ONLN d a X à d ‰ ( Ä Íchar ° d ONLN d g Xb d§ )ñ *ioNamePtr; ° d ONLN d t f à r Í ( é Íshort ° d ONLN d z fb rû )ñ
ioVRefNum; ° d ONLN d Ü t Ã Ä Í ( ú Íshort ° d ONLN d å tb Äû )ñ
ioCRefNum; ° d ONLN d ò Ç Ã é Í ( ™ Íshort ° d ONLN d û Çb éå )ñcsCode; ° d ONLN d ß ê Ã ú ( ∏ Í StreamPtr ° d ONLN d ± êb úû )ñ
udpStream; ° d ONLN d Ω û à ™ ˆ ( Δ Íunion { ° d ONLN d « ¨ Í ∏V + struct UDPCreatePB ° d ONLN d ⁄ ¨b ∏å )xcreate; ° d ONLN d ‰ ∫ Í ΔJ ( ‚struct UDPSendPB ° d ONLN d ı ∫b ΔÄ )xsend; ° d ONLN d ˝ » Í ‘\ ( struct UDPReceivePB ° d ONLN d »b ‘í )xreceive; ° d ONLN d ÷ Í ‚D ( ˛struct UDPMTUPB ° d ONLN d, ÷b ‚z )xmtu; ° d ONLN d2 ‰ à ( Í
} csParam; ° d ONLN d= Ú Æ ˛ Í ( Ã
} UDPiopb; , N Helvetica Narrow
(Ÿï C parameter-block definitions
)à27 à pÃ) ˇ@ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
0 . ° d ONLN d * T Z j +rn4
° d ONLN d A Æ Tö )Z Transmission Control Protocol , Times
° d ONLN d ™ Æ µˇ *cHThe Transmission Control Protocol (TCP) is a highly reliable, connection ° d ONLN d h ™ˇ µ ( — - ° d ONLN d i ∏ Æ √ ( fl ÃLoriented byte-stream protocol. It is designed to operate over a wide variety ° d ONLN d ∂ Δ Æ — *Lof networks and to provide virtual circuit service with orderly transmission ° d ONLN d ‘ Æ fl *Aof user data. TCP serves as the basis for a reliable interprocess ° d ONLN dE ‚ Æ Ì *Bcommunication mechanism on top of the IP layer where loss, damage, ° d ONLN dà Æ ˚Ø *8duplication, delay, or misordering of packets can occur. à pÃ) ˇ4B ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - s +<IData structures , Times
° d ONLN d 8 x CÕ +ZIThis section describes TCP Read and Write Data Structures and the receive ° d ONLN d Z F x Q Æ * buffer area.
° d ONLN d g a x n * Read and Write Data Structures
° d ONLN d Ü y x у *EThe MacTCP driver uses Read Data Structures and Write Data Structures ° d ONLN d à á x í” *I(RDS/WDS) to pass data between the user and TCP. These structures allow a ° d ONLN d ï x †‘ *Osingle read or write operation to handle multiple blocks of data; that is, they ° d ONLN df £ x Æà *Iallow scatter-read and gather-write capability. Figure 4-1 shows TCP Read ° d ONLN d∞ ± x º *and Write Data Structures.
° d ONLN d˙Ì x¯æ *DTCP does not allocate memory for storing TCP stream databases or for ° d ONLN d?˚ x± *Cbuffering received datagrams. Instead, you are required to pass TCP ° d ONLN dÉ xø *Denough memory for these purposes in the TCPCreate call. This has two ° d ONLN d» x" ≠ * advantages: , p AppleIcon p
° d ONLN d’+ x3 } *n
° d ONLN d◊) Ö4œ )
FThe buffer memory can be allocated off the application heap instead of ° d ONLN d 7 ÖB5 *'the system heap, which is very limited. p
° d ONLN dFK xS } (p ñn
° d ONLN dHI ÖT )
DYou have control over the buffering provided by TCP and can allocate ° d ONLN dçW Öb∏ *@the appropriate amount of memory for the type of application and ° d ONLN dŒe Öp ˇ *performance level desired.
° ¿ 0 i ° ¿ ° ¿ 0 J ° ¿ ° ¿ 0 j ° ¿ ° ¿ 0.5 w ° ¿ ° ¿ 10 M ° ¿ [ ° ¿ ]0 d ° ¿
° ¿ %AI3_Note:
° ¿ 0 D
° ¿ -105.031 107.0853 m
° ¿ -9.031 107.0853 L
° ¿ -9.031 247.0853 L
° ¿ -105.031 247.0853 L
° ¿ -105.031 107.0853 L
° ¿ b
° ¿ 1 g
° ¿ -107.031 109.0853 m
° ¿ -11.031 109.0853 L
° ¿ -11.031 249.0853 L
° ¿ -107.031 249.0853 L
° ¿ -107.031 109.0853 L
° ¿ b
° ¿ u
° ¿ -107.031 123.8353 m
° ¿ -11.031 123.8353 l
° ¿ S
° ¿ U
° ¿ u
° ¿ u
° ¿ 0 O
° ¿ 1 g
° ¿ 2 w ° ¿
° ¿ -4.125 175.8863 m
° ¿ -4.125 197.1363 L
° ¿ -16.375 197.1363 L
° ¿ -16.375 175.8863 L
° ¿ -4.125 175.8863 L
° ¿ f
° ¿ -10.25 186.5113 m
° ¿ F
° ¿ U
° ¿ u
° ¿ 0 g
° ¿ 0.25 w ° ¿
° ¿ -11.655 191.9533 m
° ¿ 4-11.416 191.1073 -10.537 190.6163 -9.691 190.8553 c
° ¿ 2-8.846 191.0943 -8.354 191.9743 -8.594 192.8193 c
° ¿ 3-8.833 193.6653 -9.712 194.1563 -10.558 193.9173 c
° ¿ 5-11.403 193.6783 -11.895 192.7983 -11.655 191.9533 c
° ¿ f
° ¿ -10.125 192.3863 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -11.655 185.9533 m
° ¿ 4-11.416 185.1073 -10.537 184.6163 -9.691 184.8553 c
° ¿ 2-8.846 185.0943 -8.354 185.9743 -8.594 186.8193 c
° ¿ 3-8.833 187.6653 -9.712 188.1563 -10.558 187.9173 c
° ¿ 5-11.403 187.6783 -11.895 186.7983 -11.655 185.9533 c
° ¿ f
° ¿ -10.125 186.3863 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -11.655 179.9533 m
° ¿ 4-11.416 179.1073 -10.537 178.6163 -9.691 178.8553 c
° ¿ 2-8.846 179.0943 -8.354 179.9743 -8.594 180.8193 c
° ¿ 3-8.833 181.6653 -9.712 182.1563 -10.558 181.9173 c
° ¿ 5-11.403 181.6783 -11.895 180.7983 -11.655 179.9533 c
° ¿ f
° ¿ -10.125 180.3863 m
° ¿ F
° ¿ U
° ¿ U
° ¿ u
° ¿ u
° ¿ 1 g
° ¿ 2 w ° ¿
° ¿ -101.125 175.8863 m
° ¿ -101.125 197.1363 L
° ¿ -113.375 197.1363 L
° ¿ -113.375 175.8863 L
° ¿ -101.125 175.8863 L
° ¿ f
° ¿ -107.25 186.5113 m
° ¿ F
° ¿ U
° ¿ u
° ¿ 0 g
° ¿ 0.25 w ° ¿
° ¿ -108.655 191.9533 m
° ¿ 8-108.416 191.1073 -107.537 190.6163 -106.691 190.8553 c
° ¿ 8-105.846 191.0943 -105.354 191.9743 -105.594 192.8193 c
° ¿ 8-105.833 193.6653 -106.712 194.1563 -107.558 193.9173 c
° ¿ 8-108.403 193.6783 -108.895 192.7983 -108.655 191.9533 c
° ¿ f
° ¿ -107.125 192.3863 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -108.655 185.9533 m
° ¿ 8-108.416 185.1073 -107.537 184.6163 -106.691 184.8553 c
° ¿ 8-105.846 185.0943 -105.354 185.9743 -105.594 186.8193 c
° ¿ 8-105.833 187.6653 -106.712 188.1563 -107.558 187.9173 c
° ¿ 8-108.403 187.6783 -108.895 186.7983 -108.655 185.9533 c
° ¿ f
° ¿ -107.125 186.3863 m
° ¿ F
° ¿ U
° ¿ u
° ¿ -108.655 179.9533 m
° ¿ 8-108.416 179.1073 -107.537 178.6163 -106.691 178.8553 c
° ¿ 8-105.846 179.0943 -105.354 179.9743 -105.594 180.8193 c
° ¿ 8-105.833 181.6653 -106.712 182.1563 -107.558 181.9173 c
° ¿ 8-108.403 181.6783 -108.895 180.7983 -108.655 179.9533 c
° ¿ f
° ¿ -107.125 180.3863 m
° ¿ F
° ¿ U
° ¿ U
° ¿ u
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -107.031 153.3353 m
° ¿ -11.031 153.3353 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -106.531 168.0853 m
° ¿ -10.531 168.0853 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -107.031 234.3353 m
° ¿ -11.031 234.3353 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -107.031 204.8353 m
° ¿ -11.031 204.8353 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 238.6583 0 Tp
° ¿ TP
° ¿ -31.5725 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿ ° ¿ 4 M ° ¿
° ¿ /_Helvetica-Narrow 9 Tf
° ¿ 0 Ts
° ¿ 100 Tz
° ¿ 0 Tt
° ¿ 0 TA
° ¿ 0 0 5 TC
° ¿ 100 100 200 TW
° ¿ 0 0 0 Ti
° ¿ 1 Ta
° ¿ 0 Tq
° ¿ 28 0 Tl
° ¿ 0 Tc
° ¿ 0 Tw
° ¿ (length of first buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 157.6583 0 Tp
° ¿ TP
° ¿ -31.3704 0 Td
° ¿ 0 Tr
° ¿ (length of last buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -107.031 249.0853 m
° ¿ -102.078 249.0853 l
° ¿ S
° ¿ -107.031 241.7286 m
° ¿ -102.078 241.7286 l
° ¿ S
° ¿ -107.031 234.3719 m
° ¿ -102.078 234.3719 l
° ¿ S
° ¿ -107.031 227.0152 m
° ¿ -102.078 227.0152 l
° ¿ S
° ¿ -107.031 219.6584 m
° ¿ -102.078 219.6584 l
° ¿ S
° ¿ u
° ¿ -107.031 219.6584 m
° ¿ -102.078 219.6584 l
° ¿ S
° ¿ -107.031 212.3017 m
° ¿ -102.078 212.3017 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -107.031 168.0883 m
° ¿ -102.078 168.0883 l
° ¿ S
° ¿ -107.031 160.7316 m
° ¿ -102.078 160.7316 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -107.031 160.6584 m
° ¿ -102.078 160.6584 l
° ¿ S
° ¿ -107.031 153.3017 m
° ¿ -102.078 153.3017 l
° ¿ S
° ¿ -107.031 145.945 m
° ¿ -102.078 145.945 l
° ¿ S
° ¿ -107.031 131.2316 m
° ¿ -102.078 131.2316 l
° ¿ S
° ¿ -107.031 138.695 m
° ¿ -102.078 138.695 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -107.031 131.1584 m
° ¿ -102.078 131.1584 l
° ¿ S
° ¿ -107.031 123.8017 m
° ¿ -102.078 123.8017 l
° ¿ S
° ¿ -107.031 116.445 m
° ¿ -102.078 116.445 l
° ¿ S
° ¿ -107.031 109.0883 m
° ¿ -102.078 109.0883 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 217.4083 0 Tp
° ¿ TP
° ¿ -32.8008 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿
° ¿ (pointer to first buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 137.4083 0 Tp
° ¿ TP
° ¿ -32.5986 0 Td
° ¿ 0 Tr
° ¿ (pointer to last buffer) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 114.4083 0 Tp
° ¿ TP
° ¿ -18.6504 0 Td
° ¿ 0 Tr
° ¿ (zero \(word\)) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ 0 R
° ¿ 0 G
° ¿ 0.5 w ° ¿
° ¿ -16.281 241.7286 m
° ¿ -11.328 241.7286 l
° ¿ S
° ¿ -16.281 227.0152 m
° ¿ -11.328 227.0152 l
° ¿ S
° ¿ -16.281 219.6584 m
° ¿ -11.328 219.6584 l
° ¿ S
° ¿ u
° ¿ -16.281 219.6584 m
° ¿ -11.328 219.6584 l
° ¿ S
° ¿ -16.281 212.3017 m
° ¿ -11.328 212.3017 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -16.281 160.6584 m
° ¿ -11.328 160.6584 l
° ¿ S
° ¿ -16.281 153.3017 m
° ¿ -11.328 153.3017 l
° ¿ S
° ¿ -16.281 145.945 m
° ¿ -11.328 145.945 l
° ¿ S
° ¿ -16.281 131.2316 m
° ¿ -11.328 131.2316 l
° ¿ S
° ¿ -16.281 138.695 m
° ¿ -11.328 138.695 l
° ¿ S
° ¿ U
° ¿ u
° ¿ -16.281 131.1584 m
° ¿ -11.328 131.1584 l
° ¿ S
° ¿ -16.281 123.8017 m
° ¿ -11.328 123.8017 l
° ¿ S
° ¿ -16.281 116.445 m
° ¿ -11.328 116.445 l
° ¿ S
° ¿ -16.281 109.0883 m
° ¿ -11.328 109.0883 l
° ¿ S
° ¿ U
° ¿ 0 To
° ¿ 1 0 0 1 -58.578 253.1583 0 Tp
° ¿ TP
° ¿
-8.8154 0 Td
° ¿ 0 Tr
° ¿ 0 O
° ¿ 0 g
° ¿ 1 w ° ¿
° ¿ (8 bits) ° ¿ Tx ° ¿
° ¿ (\r) TX ° ¿
° ¿ TO
° ¿ U
° ¿ U
° ¿ %%PageTrailer
° ¿
%%Trailer
° ¿ +Adobe_IllustratorA_AI3 /terminate get exec
° ¿ )Adobe_typography_AI3 /terminate get exec
° ¿ &Adobe_customcolor /terminate get exec
° ¿ Adobe_cshow /terminate get exec
° ¿ $Adobe_cmykcolor /terminate get exec
° ¿ &Adobe_packedarray /terminate get exec
° ¿ %%EndDocument
† ø † ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! Æ , +ÃHFThe buffer area for incoming datagrams belongs to the MacTCP driver as ° d ONLN d G / Æ : *Ilong as the TCP stream is open. When TCPRelease is called, this memory is ° d ONLN d ë = Æ H‰ *Ereturned to you and you can then reuse it or return it to the system. ° d ONLN d ◊ R Æ ]¯ *EAn application should allocate memory by first finding the MTU of the ° d ONLN d ` Æ kˇ *Dphysical network (see the UDPMTU section in Chapter 3). Some network ° d ONLN db n Æ y” *<devices supported by MacTCP have very large MTU sizes. If an ° d ONLN dü | Æ á *Happropriate amount of memory is not allocated to the TCP connection, the ° d ONLN dË ä Æ ï¸ *Cconnection will behave unpredictably. The minimum memory allocation ° d ONLN d, ò Æ £ *Hshould be 4N + 1024, where N is the size of the physical MTU returned by ° d ONLN du ¶ Æ ± *the UDPMTU call. , N Helvetica Narrow
° d ONLN dÜ Ã T ⁄ å ( ˆ r Using TCP
° d ONLN dê Â Æ +Z<This section describes how to send and receive TCP segments.
° d ONLN dÕ Æ
3 * Streams and connections
° d ONLN d Æ# *GA TCP stream supports one connection at a time. But a TCP connection on ° d ONLN d-& Æ1˚ *Fa stream can be closed and another connection opened without releasing ° d ONLN dt4 Æ?Û *Athe TCP stream. The MacTCP driver can support 64 open TCP streams ° d ONLN d∂B ÆM ˆ *simultaneously.
° d ONLN dΔ] Æjc * !Asynchronous notification routine
° d ONLN dËu ÆÄ *JWhen a TCP stream is created, a routine can be registered that TCP uses to ° d ONLN d3É ÆéÁ *Cnotify you of asynchronous events relevant to that TCP stream. This ° d ONLN dwë Æú *>routine is called the asynchronous notification routine (ASR). ° d ONLN d∂¶ Ʊ¸ *EExamples of events that the MacTCP driver communicates to the user by ° d ONLN d¸¥ ÆøM * means of an ASR include Timeout ° d ONLN d¥MøP )ü ° d ONLN d ¥Pø )%Expired, Data Arrived, and Connection ° d ONLN dB¬ ÆÕÓ (È ÃGTerminated. Since the ASR is called from the interrupt level, it cannot ° d ONLN dä– Æ€Ï *Ballocate or release memory. In addition, synchronous MacTCP driver ° d ONLN dÕfi ÆÈr *&commands cannot be issued from an ASR.
° d ONLN dÙ˘ Æ * Connection opening
° d ONLN d Æ *ETo listen for an incoming connection, use the TCPPassiveOpen command. ° d ONLN dM Æ*¸ *CThis command can be used to specify whether any incoming connection ° d ONLN dë- Æ8¸ *Hwill be accepted or only connections from a particular remote IP address ° d ONLN d⁄; ÆF Ô *
and TCP port. ° d ONLN dËP Æ[Í *@To initiate outgoing connections, use the TCPActiveOpen command. (Ÿ‚ Using TCP
° d ONLN dhÑ xè *GTCP normally provides some timeout services to the upper-layer protocol ° d ONLN d∞í xù“ *L(ULP). This timeout service is known as the ULP timeout. If there is data to ° d ONLN d˝† x´‘ *Ksend on a connection, but for some specified period of time the data cannot ° d ONLN dIÆ xπÕ *Lbe sent (either because the remote TCP is not set to receive any data or the ° d ONLN dñº x«» *Hdata has been sent but the remote TCP has not acknowledged it), then the ° d ONLN dfl x’ ⁄ *ULP timeout expires. ° d ONLN dÙfl xÍ√ *DWhen the ULP timeout expires, TCP executes the specified ULP timeout ° d ONLN d9Ì x¯Δ *Jaction. There are two possible actions: abort the connection or report the ° d ONLN dÑ˚ xÜ *:timer expiration by means of an ASR and restart the timer. ° d ONLN dø x¶ *@In addition to this normal TCP timer, the MacTCP driver provides ° d ONLN d x)¡ *Ccommand timeouts on commands that are not subject to the ULP timer. ° d ONLN dD, x7ª *<These commands are TCPPassiveOpen, TCPNoCopyRcv, and TCPRcv.
(Ÿ <32
))Chapter 4 / Transmission Control Protocol à :ÃÛ ˇ
™ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! Æ ,Ê +ÃH>A TCPPassiveOpen command instructs TCP to wait for an incoming ° d ONLN d ? / Æ : *Nconnection. The ULP timer is not started until the first connection initiation ° d ONLN d é = Æ HÙ *Asegment arrives. To prevent a TCPPassiveOpen command from waiting ° d ONLN d – K Æ VÎ *Eindefinitely for a connection initiation segment to arrive, a command ° d ONLN d Y Æ d *Ktimeout is provided. If no connection initiation segment is received within ° d ONLN db g Æ r *Ethe specified timeout period, the TCPPassiveOpen command is completed ° d ONLN d® u Æ Ä *with an error code. ° d ONLN dº ä Æ ï¸ *ASimilarly, the TCPNoCopyRcv and TCPRcv commands are not protected ° d ONLN d˛ ò Æ £˝ *Cby the ULP timer. In the absence of command timeouts, both commands ° d ONLN dB ¶ Æ ± *Mcould wait indefinitely for data to arrive. If a command timeout is specified ° d ONLN dê ¥ Æ øÊ *:on a TCPNoCopyRcv or TCPRcv command, the command is always ° d ONLN dÀ ¬ Æ Õ˘ *Jcompleted within the specified time period. If no data has arrived at that ° d ONLN d – Æ €˚ *Hpoint, the command is completed with an error. If some data has arrived, ° d ONLN d_ fi Æ È *Jthe command is completed successfully, returning the data that has arrived ° d ONLN d™ Ï Æ ˜ À *so far. , N Helvetica Narrow
° d ONLN d≤ Æ * Pushed data
° d ONLN dæ Æ*‹ *@Usually, TCP is allowed to collect data sent by means of TCPSend ° d ONLN dˇ- Æ8 *Icommands and to send that data in segments, as convenient. By setting the ° d ONLN dI; ÆFÒ *CPush flag in the TCPSend command, TCP can be instructed to send all ° d ONLN dçI ÆT *unsent data at once. ° d ONLN d¢^ Æi˚ *LSimilarly, TCP is allowed to collect received data internally and deliver it ° d ONLN dÔl Æw *Jwith reasonable promptness to the user. However, when pushed data arrives, ° d ONLN d:z ÆÖß *7TCP immediately delivers all received data to the user. ° d ONLN drè ÆöÓ *GNote that there is no necessary relationship between the Push flag in a ° d ONLN d∫ù Æ® *BTCPSend command and segment boundaries. The push function does not ° d ONLN d˝´ Æ∂ò */provide a method of marking message boundaries.
° d ONLN d-Δ Æ” Ò * Urgent mode
° d ONLN d9fi ÆÈÔ *BThe urgent mechanism for TCP allows the sending user to prompt the ° d ONLN d|Ï Æ˜˘ *Jreceiving user to accept urgent data. It also permits the receiving TCP to ° d ONLN d«˙ ÆÛ *Gindicate to the receiving user when all currently known urgent data has ° d ONLN d Æ *been received. ° d ONLN d Æ( *HTCP does not define what the user is required to do when in urgent mode, ° d ONLN dg+ Æ6 *Obut the general practice is that the receiving user takes action to process the ° d ONLN d∑9 ÆD *arriving data quickly. ° d ONLN dŒN ÆY˚ *FA receiving user can be put in urgent mode in two ways: by means of an ° d ONLN d\ Æg˘ *@Urgent flag in a TCPNoCopyRcv or TCPRcv command, or by an urgent ° d ONLN dVj Æu *GASR notification. The user is always taken out of urgent mode by a Mark ° d ONLN dûx ÆÉ *Fflag in the TCPNoCopyRcv or TCPRcv command that contains the last byte ° d ONLN dÂÜ Æë Ú *of urgent data. (Ÿ‚ Using TCP
° d ONLN d¿? xJÀ *GTCP closes communications gracefully. All outstanding Send requests are ° d ONLN dM xX≈ *Gtransmitted and acknowledged before the connection is allowed to close. ° d ONLN dP[ xfÆ *=You can issue several TCPSend commands followed by a TCPClose ° d ONLN déi xt‘ *Lcommand and expect that all the data will be sent successfully to the remote ° d ONLN d€w xÇ è *TCP. ° d ONLN d·å xó… *CA TCPClose command means “I have no more data to send,” but it does ° d ONLN d%ö x•¿ *Dnot mean “I will receive no more data” or “shut down this connection ° d ONLN dj® x≥… *Eimmediately.” A connection may remain open indefinitely as the remote ° d ONLN d∞∂ x¡° *<TCP continues to send data after a TCPClose command has been ° d ONLN d̃ xœÃ *Ccompleted. When the remote TCP also issues a close command—and only ° d ONLN d1“ x›” *Fthen—the connection is closed. A TCPRcv command should be issued after ° d ONLN dx‡ xÎÕ *Ga TCPClose command has been completed to make sure that all the data is ° d ONLN d¿Ó x˘ ° * received. ° d ONLN d x» *KIf the desired effect is to break the connection without any assurance that ° d ONLN d x Ü *;all data in transit is delivered, use the TCPAbort command.
° d ONLN dR, x9' * Network management information
° d ONLN drD xOæ *ATCP keeps two types of network management information: global TCP ° d ONLN d¥R x]¬ *Hinformation and stream-specific information, which is relevant only to a ° d ONLN d˝` xk » *particular stream.
. ° d ONLN d ! Æ ,ˇ +ÃHBThe TCPGlobalInfo command makes global TCP information accessible. ° d ONLN d C / Æ :˙ *GThis command returns pointers to the actual structures where TCP stores ° d ONLN d ã = Æ H¸ *Kthis information. Thus, the user has read-write access to this information. ° d ONLN d ◊ R Æ ]¯ *CThe TCPStatus command makes stream-specific information accessible. ° d ONLN d ` Æ k‹ *AMost stream-specific information is copied into the TCPStatus I/O ° d ONLN d] n Æ y¸ *Jparameter block, giving the user read-only access. But a direct pointer to ° d ONLN d® | Æ áˇ *Othe traffic statistics allows the user read-write access to those counters (see ° d ONLN d¯ ä Æ ïõ *3the section “TCPGlobalInfo” later in this chapter). , N Helvetica Narrow
° d ONLN d, • Æ ≤Q * Formatting MacTCP commands
° d ONLN dG Ω Æ »¸ *HIn most cases, a 0 value for a parameter in an I/O parameter block means ° d ONLN dê À Æ ÷ˇ *Lthat TCP will use its default value. Thus, you must initialize I/O parameter ° d ONLN d› Ÿ Æ ‰¸ *Jblocks and then fill in the required parameters, plus optional parameters.
° d ONLN d( ˇ T
ò () r TCP routines
° d ONLN d5 Æ#Ï +ZGThis section presents calls to the TCP driver. Table 4-1 lists each TCP ° d ONLN d}& Æ1 *routine and its function.
° d ONLN dòB ÆM ” * Table 4-1 ° d ONLN d°B ”M )% TCP routines
° d ONLN d∞V Æ^ « ({ ÃRoutine ° d ONLN d∏V^$ )ZFunction o o) Å Å)
° d ONLN d¡h Æs ⁄ (è Ã TCPCreate ° d ONLN dÀhsU )ZOpens a TCP stream ° d ONLN dfiw ÆÇ Ô (û ÃTCPPassiveOpen ° d ONLN dÌwÇÑ )Z"Listens for an incoming connection ° d ONLN dÜ Æë Î (≠ Ã
TCPActiveOpen ° d ONLN d Üë† )Z*Initiates an outgoing call to a remote TCP ° d ONLN dIï Ɔ ” (º ÃTCPSend ° d ONLN dQï†é )Z$Sends specified data on a connection ° d ONLN dv§ ÆØ Î (À à TCPNoCopyRcv ° d ONLN dɧØÀ )Z5Retrieves data that has been received on a connection ° d ONLN dπ≥ Ææ Ë (⁄ à TCPBfrReturn ° d ONLN dΔ≥æƒ )Z2Returns a set of receive buffers to the TCP driver ° d ONLN d˘¬ ÆÕ Œ (È ÃTCPRcv ° d ONLN d ¬ÕÀ )Z5Retrieves data that has been received on a connection ° d ONLN d6— Æ‹ ‘ (¯ ÃTCPClose ° d ONLN d?—‹Õ )Z7Signals that the user has no more data to send on this ° d ONLN dw›Ë. *
connection ° d ONLN dÇÏ Æ˜ ◊ ( ÃTCPAbort ° d ONLN dãϘæ )Z1Terminates the connection without trying to send ° d ONLN dΩ¯† * )outstanding data or deliver received data ° d ONLN dÁ Æ ⁄ (. à TCPStatus ° d ONLN dÒ” )Z5Extracts information from TCP regarding a particular ° d ONLN d' . *
connection ° d ONLN d2" Æ- ‹ (I Ã
TCPRelease ° d ONLN d="-V )ZCloses a TCP stream ° d ONLN dQ1 Æ< Â (X Ã
TCPGlobalInfo ° d ONLN d_1<
)ZFAllows the user access to global statistics and parameters that affect ° d ONLN d¶=HW * the operation of TCP p p)
+≤u TCP routines
)E35 Ã pÃ) ˇ
◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - [ +<I TCPCreate , Times
° d ONLN d
8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d $ 8 ˇ C^ )-csCode = TCPCreate ° d ONLN d 7 I x U É ( q ñ¨ ° d ONLN d 9 J • U ± )-28 ° d ONLN d < J “ U Á )-long ° d ONLN d A J ˇ UA )-stream pointer ° d ONLN d P [ x g É ( É ñÆ ° d ONLN d R \ • g ± )-32 ° d ONLN d U \ “ g Á )-long ° d ONLN d Z \ ˇ gÖ )- pointer to receive buffer area ° d ONLN d y m x y É ( ï ñÆ ° d ONLN d { n • y ± )-36 ° d ONLN d ~ n “ y Á )-long ° d ONLN d É n ˇ yÇ )- length of receive buffer area ° d ONLN d ° x ã É ( ß ñÆ ° d ONLN d £ Ä • ã ± )-40 ° d ONLN d ¶ Ä “ ã Á )-long ° d ONLN d ´ Ä ˇ ãD )-pointer to ASR ° d ONLN d ∫ ë x ù É ( π ñÆ ° d ONLN d º í • ù ± )-44 ° d ONLN d ø í “ ù Á )-long ° d ONLN d ƒ í ˇ ùL )-user data pointer ° d ONLN d ÷ ß x ≤Δ ( Œ ñETCPCreate opens a TCP stream. A TCP stream is not equivalent to a TCP ° d ONLN d µ x ¿“ *Iconnection. The MacTCP driver returns a pointer to a stream database. The ° d ONLN df √ x Œœ *Istream pointer is an input parameter in all subsequent commands affecting ° d ONLN d∞ — x ‹ ™ * the stream. ° d ONLN dº Ê x Ò∂ *DThe receive buffer area is a block of memory that TCP uses to buffer ° d ONLN d Ù x ˇ¡ *Cincoming segments. Ownership of this block of memory passes to TCP. ° d ONLN dE x
invalidLength ° d ONLN dµÍ ˇıù )á$the receive buffer area is too small ° d ONLN d⁄¸ x µ (# ñ
invalidBufPtr ° d ONLN d˸ ˇù )á$the receive buffer area pointer is 0 ° d ONLN d
x ⁄ (5 ñinsufficientResources ° d ONLN d# ˇó )á 64 TCP streams are already open
(Ÿ <36
))Chapter 4 / Transmission Control Protocol à :ÃÛ ˇ F ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d Æ ,Z +ÃH%TCP asynchronous notification routine , Times
° d ONLN d & 6 Æ AÈ *BThe TCP asynchronous notification routine (ASR) is a user-supplied ° d ONLN d i D Æ O˝ *Hroutine called by TCP to notify you of asynchronous events relevant to a ° d ONLN d ≤ R Æ ] *Jparticular TCP stream. You register this routine with TCP in the TCPCreate ° d ONLN d ˝ ` Æ k ¡ *call. ° d ONLN d u Æ Äˆ *NSince this routine is called at interrupt level, it cannot release or allocate ° d ONLN dR É Æ é *?memory. An ASR routine can issue additional asynchronous MacTCP ° d ONLN dí ë Æ ú „ *
driver calls. ° d ONLN d† ´ Æ ∂s *+The C description of the ASR is as follows: ,
Courier
° d ONLN dà º Æ » * pascal void ° d ONLN dÿ º »b )ZTCPNotifyProc ( ° d ONLN dÎ ÷Ä *StreamPtr tcpStream, ° d ONLN d ÿ ‰û *unsigned short eventCode, ° d ONLN d Ê Úh *Ptr userDataPtr, ° d ONLN d4 Ù ∞ * unsigned short terminReason, ° d ONLN dT∞ * struct ICMPReport *icmpMsg);
° d ONLN dq Æ#˜ (? ÃGRegister A1 contains a pointer to the Internet Control Message Protocol ° d ONLN dπ& Æ1Î *D(ICMP) report structure if the event code in D0 is ICMP received, A2 ° d ONLN d˛4 Æ?˛ *Lcontains the user data pointer, A5 is already set up to point to application ° d ONLN dKB ÆM˘ *Gglobals, D0 (word) contains an event code, and D1 contains a reason for ° d ONLN dìP Æ[ Ê * termination. ° d ONLN d†e Tp ã (å r Event codes ° d ONLN d¨e Æp œ )Zclosing ° d ONLN d¥e5p )á-all data on this connection has been received ° d ONLN d‰s5~s *
and delivered ° d ONLN dÚÖ Æê È (¨ à ULP timeout ° d ONLN d˛Ö5ê˛ )á)no response from the remote TCP; reported ° d ONLN d(ì5û *-only if TCP is configured to report a timeout ° d ONLN dV°5¨” *"instead of aborting the connection ° d ONLN dy≥ Ææ Ÿ (⁄ à terminate ° d ONLN dÉ≥5æ¥ )áconnection no longer exists ° d ONLN dü≈ Æ– · (Ï Ã data arrival ° d ONLN d¨≈5–‘ )á!data arrived, no receive commands ° d ONLN dŒ”5fik * outstanding ° d ONLN d⁄Â Æ ( Ãurgent data outstanding ° d ONLN dÚÂ5à )á user should go into urgent mode ° d ONLN d˜ Æ ( ÃICMP message received ° d ONLN d(˜5‚ )á$an Internet Control Message has been ° d ONLN dM5 *-received on the stream; register A1 points to ° d ONLN d{5 Ä *the ICMP report ° d ONLN dã- Æ8 (T ÃKFor the terminate event, a reason for connection termination is given in D1 ° d ONLN d◊; ÆF – *(word): ° d ONLN dflM ÆX È * remote abort ° d ONLN dÏM5XÍ )á%the remote TCP aborted the connection ° d ONLN d_ Æj Ù (Ü Ãnetwork failure ° d ONLN d"_5jè )ácurrently not in use ° d ONLN d7q Æ| (ò Ãsecurity/precedence ° d ONLN dLq5|¯ )á+invalid security option or precedence level ° d ONLN dx Æä ⁄ (¶ Ãmismatch (Ÿÿ TCP routines
x” *IAn ICMP message reports an error in the processing of a datagram that was ° d ONLN d¶ x&Ã *Hsent on a TCP stream. When an ICMP message is received, a data structure ° d ONLN dÔ) x4¿ *His passed up by TCP to the client to describe the received message. This ° d ONLN d87 xBö *@data structure, called an ICMP report, has the following format: ° d ONLN dyI xT ~ *0 ° d ONLN d{I •T º )-word ° d ONLN dÄI “T )-stream pointer ° d ONLN dè[ xf ~ (Ç ñ2 ° d ONLN dë[ •f ∫ )-long ° d ONLN dñ[ “fH )-local IP address of stream ° d ONLN d±m xx ~ (î ñ6 ° d ONLN d≥m •x º )-word ° d ONLN d∏m “xC )-local TCP port of stream ° d ONLN d— xä ~ (¶ ñ8 ° d ONLN d” •ä ∫ )-long ° d ONLN dÿ “ä√ )-4remote IP address (destination of original datagram) , N Helvetica Narrow
time exceeded ° d ONLN dM Æ ¥ (* Ã7 ° d ONLN dO €3 )-parameter problem ° d ONLN da Æ ¥ (< Ã8 ° d ONLN dc € I )-missing required option ° d ONLN d{1 Æ<I (X Ã!Codes 0–3 are defined as follows: , p AppleIcon p
° d ONLN dùE ÆM ≥ *n
° d ONLN düC ªN„ )
ANet unreachable indicates that, according to the information in a ° d ONLN d·Q ª\ *Kgateway routing table, the network specified in the IP destination field of ° d ONLN d-_ ªjH * a TCP segment is unreachable. p
° d ONLN dKs Æ{ ≥ (ò Ãn
° d ONLN dMq ª|Ï )
BHost unreachable indicates that a gateway determined that the host ° d ONLN dê ªä¯ *Fspecified in the IP destination field of a TCP segment is unreachable. p
° d ONLN d◊ì Æõ ≥ (∏ Ãn
° d ONLN dŸë ªú )
FProtocol unreachable indicates that a TCP segment was delivered to the ° d ONLN d ü ª™˜ *Fdestination host, but there was no process on that host to receive TCP ° d ONLN dg≠ ª∏ Ë * segments. p
° d ONLN dq¡ Æ… ≥ (Ê Ãn
° d ONLN dsø ª Ì )
BPort unreachable indicates that a TCP segment was delivered to the ° d ONLN d∂Õ ªÿ‡ *Bdestination host, but there was no client of TCP listening on that ° d ONLN d˘€ ªÊ *particular TCP port. ° d ONLN d˜ Æ ( ÃIIf the TCP stream is configured for the ULP abort timeout action, the TCP ° d ONLN dX ÆÓ *Fclient need not take any action in response to destination unreachable ° d ONLN dü Æ e *'messages (they are informational only). ° d ONLN d«( Æ3À *ATCP breaks the connection if there is data to send, but it is not ° d ONLN d 6 ÆA *Hacknowledged within the ULP timeout period. If, however, this TCP stream ° d ONLN dRD ÆO *Hhas been configured for the ULP report timeout action, then the TCP user ° d ONLN dõR Æ]Ú *Ghas taken responsibility for deciding when and if the remote host is no ° d ONLN d„` Æk´ *6longer available, and the connection should be broken. , N Helvetica Narrow (Ÿÿ TCP routines
)E39 à pÃ) ˇ\ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x ,” +ñHJA single destination unreachable message should not be taken too seriously ° d ONLN d K / x :— *Gbecause such messages may be received occasionally when the topology of ° d ONLN d ì = x H¬ *Ethe internet changes. But if several successive TCPSend commands each ° d ONLN d Ÿ K x Vœ *Kresult in an ICMP report indicating destination unreachable, the TCP client ° d ONLN d% Y x dµ *Eshould assume that the remote host has either crashed or is no longer ° d ONLN dk g x rB *+accessible and should break the connection. ° d ONLN dó É x é * !Codes 4–8 are defined as follows: , p AppleIcon p
° d ONLN dπ ó x ü } *n
° d ONLN dª ï Ö †¿ )
DFragmentation required indicates that the TCP user has set the Don’t ° d ONLN d £ Ö Æπ *=Fragment flag in a TCPOpen command, yet a segment on that TCP ° d ONLN d> ± Ö ºï *<connection could not be delivered to its destination without ° d ONLN d{ ø Ö π *Bfragmentation. To avoid this, don’t set the Don’t Fragment flag on ° d ONLN dæ Õ Ö ÿ Í *TCPOpen commands. p
° d ONLN d– · x È } ( ñn
° d ONLN d“ fl Ö Íƒ )
GSource route failed indicates that the TCP user has specified the route ° d ONLN d Ì Ö ¯Õ *Ithis datagram should take in the IP options but that particular route was ° d ONLN dd ˚ Ö ¬ *not available. p
° d ONLN ds x } (4 ñn
° d ONLN du
Ö… )
DTime exceeded indicates that the Time to Live specified in a TCPOpen ° d ONLN d∫ Ö&« *Bcommand was too short to allow a TCP segment on this TCP stream to ° d ONLN d˝) Ö4≠ *Abe delivered through all the necessary gateways on the way to its ° d ONLN d?7 ÖB∏ *Cdestination. A longer Time to Live value should be specified in the ° d ONLN dÉE ÖP Ê *TCPOpen command. p
° d ONLN dîY xa } (~ ñn
° d ONLN dñW ÖbÀ )
DParameter problem indicates that the IP header used on a TCP segment ° d ONLN d€e ÖpÆ *Awas not acceptable by either an intermediate gateway or the final ° d ONLN d s Ö~∏ *Bdestination. The additional information pointer in the ICMP report ° d ONLN d`Å Öå± *Cstructure points to a static copy of the IP header used for sending ° d ONLN d§è Ööº *Asegments on this TCP connection. The additional information value ° d ONLN dÊù Ö®ø *Dindicates a byte offset in the IP header where the parameter problem ° d ONLN d+´ Ö∂Ω *Fexists. For example, an offset of 1 indicates that the Type of Service ° d ONLN drπ ÖƒÕ *Mfield is invalid, and an offset of 20 indicates that the first option present ° d ONLN d¿« Ö“ ± * is invalid. p
° d ONLN dÀ x„ } ( ñn
° d ONLN dŒŸ Ö‰∑ )
AMissing required option means that the remote TCP requires that a ° d ONLN dÁ ÖÚ *Gspecific IP option be present in the IP header. The IP option type code ° d ONLN dXı Ö ù *>that is required by the remote TCP is passed in the additional ° d ONLN dó Ö ◊ *information field. ° d ONLN d™ x*‘ (F ñKMuch of the information that asynchronous notifications pass to you is also ° d ONLN dˆ- x8Ã *Javailable in other ways. For example, you can tell that the remote TCP has ° d ONLN dA; xF¥ *Fclosed a connection either by waiting for a closing notification or by ° d ONLN dàI xTÑ *7submitting TCPRcv commands until one is returned with a ° d ONLN d¿W xb Î *connectionClosing error. , N Helvetica Narrow
° d ONLN d 8 T C † *Parameter block , Symbol ° d ONLN d 7 Æ C π )ZÆ ° d ONLN d ! 8 € C Á )-26 ° d ONLN d $ 8 C )-word ° d ONLN d ) 85 C∞ )-csCode = TCPPassiveOpen ° d ONLN d A I Æ U π ( q ÃÆ ° d ONLN d C J € U Á )-28 ° d ONLN d F J U )-long ° d ONLN d K J5 Uw )-stream pointer ° d ONLN d Z [ Æ g π ( É ÃÆ ° d ONLN d \ \ € g Á )-32 ° d ONLN d _ \ g )-byte ° d ONLN d d \5 g )--ULP timeout value in seconds; 0 = use default ° d ONLN d í m Æ y π ( ï ÃÆ ° d ONLN d î n € y Á )-33 ° d ONLN d ó n y )-byte ° d ONLN d ú n5 yΔ )- ULP timeout action; 0 = report, ° d ONLN d Ω |5 áÄ *nonzero = abort ° d ONLN d Õ ç Æ ô π ( µ ÃÆ ° d ONLN d œ é € ô Á )-34 ° d ONLN d “ é ô )-byte ° d ONLN d ◊ é5 ôŸ )-%validity bits for optional parameters ° d ONLN d ˝ ü Æ ´ π ( « ÃÆ ° d ONLN d ˇ † € ´ Á )-35 ° d ONLN d † ´ )-byte ° d ONLN d †5 ´˜ )-(command timeout in seconds; 0 = infinity ° d ONLN d0 ± Æ Ω π ( Ÿ ô ° d ONLN d2 ≤ € Ω Á )-36 ° d ONLN d5 ≤ Ω )-long ° d ONLN d: ≤5 Ω¥ )-remote IP address; can be 0 ° d ONLN dV √ Æ œ π ( Πô ° d ONLN dX ƒ € œ Á )-40 ° d ONLN d[ ƒ œ )-word ° d ONLN d` ƒ5 œØ )-remote TCP port; can be 0 ° d ONLN dz ’ Æ · π ( ˝ è ° d ONLN d| ÷ € · Á )-42 ° d ONLN d ÷ · )-long ° d ONLN dÑ ÷5 ·} )-local IP address ° d ONLN dï Á Æ Û π ( ô ° d ONLN dó Ë € Û Á )-46 ° d ONLN dö Ë Û )-word ° d ONLN dü Ë5 Û¸ )-+local TCP port; if 0, TCP assigns an unused ° d ONLN dÀ ˆ5H *port ° d ONLN d– Æ π (/ ÃÆ ° d ONLN d“ € Á )-48 ° d ONLN d’ )-byte ° d ONLN d⁄5x )-type of service ° d ONLN dÍ Æ% π (A ÃÆ ° d ONLN dÏ €% Á )-49 ° d ONLN dÔ% )-byte ° d ONLN dÙ5%i )-
precedence ° d ONLN dˇ+ Æ7 π (S ÃÆ ° d ONLN d, €7 Á )-50 ° d ONLN d,7 )-byte ° d ONLN d ,57ë )-don’t fragment flag ° d ONLN d = ÆI π (e ÃÆ ° d ONLN d > €I Á )-51 ° d ONLN d">I )-byte ° d ONLN d'>5Ih )- time to live ° d ONLN d4O Æ[ π (w ÃÆ ° d ONLN d6P €[ Á )-52 ° d ONLN d9P[ )-byte ° d ONLN d>P5[n )-
security flag ° d ONLN dLa Æm π (â ÃÆ ° d ONLN dNb €m Á )-53 ° d ONLN dQbm )-byte ° d ONLN dVb5m} )-IP option count ° d ONLN dfs Æ π (õ ÃÆ ° d ONLN dht € Á )-54 ° d ONLN dkt )-var. ° d ONLN dpt5d )-
. ° d ONLN d ! x ,Æ +ñHCIf the remote IP address and remote TCP port are 0, a connection is ° d ONLN d D / x :± *Baccepted from any remote TCP. If they are nonzero, a connection is ° d ONLN d á = x H… *Jaccepted only from that particular remote TCP. If the local TCP port is 0, ° d ONLN d “ K x V *!TCP assigns an unused port value. ° d ONLN d Ù ` x k¿ *HIf a connection is partly established but cannot be completed within the ° d ONLN d= n x yŒ *JULP timeout period after the first connection opening segment arrives, the ° d ONLN dà | x áà *LULP action is taken. If the ULP timeout action is abort (the default value), ° d ONLN d’ ä x ïÕ *Dthe connection is broken and the TCPPassiveOpen command is completed ° d ONLN d ò x £Õ *Kin error. If the ULP timeout action is report, an ASR call informs the ULP, ° d ONLN df ¶ x ±” *Iand the ULP timer is restarted. The minimum value of the ULP timeout is 2 ° d ONLN d∞ ¥ x ø≤ *Dseconds; 0 means that TCP should use its default value of 2 minutes. ° d ONLN dı … x ‘Ω *DIf no connection opening packet arrives within the specified command ° d ONLN d: ◊ x ‚” *Ftimeout period after the TCPPassiveOpen command is issued, the command ° d ONLN dÅ Â x √ *Dis completed in error. The minimum value of the command timeout is 2 ° d ONLN dΔ Û x ˛ Ô *seconds; 0 means infinite. ° d ONLN d· xœ *JYou have control over many fields in the IP header of all segments sent on ° d ONLN d, x!≥ *Ethis connection. You can set these fields only when the connection is ° d ONLN dr$ x/T *.opened. They stay fixed during the connection. ° d ONLN d¢@ xK * %The type of service is a 3-bit field: ° d ONLN d»R x] ç *bit 0 ° d ONLN dŒR “] )Zset for low delay ° d ONLN d‡d xo ç (ã ñbit 1 ° d ONLN dÊd “o> )Zset for high throughput ° d ONLN d˛v xÅ ç (ù ñbit 2 ° d ONLN dv “Å6 )Zset for high reliability ° d ONLN d ã xñƒ (≤ ñEFor example, a value of 0x02 means high throughput. The default value ° d ONLN dcô x§ ã *is 0. ° d ONLN diµ x¿ * $Precedence has the following values: ° d ONLN dé« x“ ~ *0 ° d ONLN dê« •“ Δ )-routine ° d ONLN dòŸ x‰ ~ ( ñ1 ° d ONLN döŸ •‰ » )-priority ° d ONLN d£Î xˆ ~ ( ñ2 ° d ONLN d•Î •ˆ ’ )- immediate ° d ONLN dØ˝ x ~ ($ ñ3 ° d ONLN d±˝ • ª )-flash ° d ONLN d∑ x ~ (6 ñ4 ° d ONLN dπ • Â )-flash-override ° d ONLN d»! x, ~ (H ñ5 ° d ONLN d ! •, fl )-
CRITIC/ECP ° d ONLN d’3 x> ~ (Z ñ6 ° d ONLN d◊3 •> )-internetwork control ° d ONLN dÏE xP ~ (l ñ7 ° d ONLN dÓE •P Ó )-network control ° d ONLN d˛Z xe& (Å ñ&The default value for precedence is 0. , N Helvetica Narrow
(Ÿ <42
))Chapter 4 / Transmission Control Protocol à :ÃÛ ˇ
Z ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! Æ , +ÃHKIf the Don’t Fragment flag is nonzero, all segments sent on this connection ° d ONLN d L / Æ : *Hare prohibited from being fragmented by the local IP or any intermediate ° d ONLN d ï = Æ H *KIP. If a segment cannot be delivered without fragmentation, it’s discarded. ° d ONLN d · R Æ ]Ê *AThe Time to Live indicates the maximum time that segments on this ° d ONLN d# ` Æ kÎ *Fconnection are allowed to remain in the internet system. This value is ° d ONLN dj n Æ y„ *Ddecreased by every IP module that processes the segment; thus, it is ° d ONLN dØ | Æ á *Geffectively a maximum hop count (the number of times a segment can pass ° d ONLN d˜ ä Æ ïˇ *Ethrough a module). The minimum value is 2; 0 means TCP should use its ° d ONLN d= ò Æ £\ *(default value (the default value is 60). ° d ONLN df ≠ Æ ∏‰ *FIf the Security flag is nonzero, TCP inserts its configured default IP ° d ONLN d≠ ª Æ Δ
*Osecurity option into all segments sent on this connection. In addition, for all ° d ONLN d˝ … Æ ‘Í *Garriving segments that contain a security option, TCP verifies that the ° d ONLN dE ◊ Æ ‚Ì *Hsecurity matches the configured default security. Note that this flag is ° d ONLN dé Â Æ Ê *Grelevant only if no security option is present in the user-specified IP ° d ONLN d÷ Û Æ ˛ ” *options. ° d ONLN dfl Ƈ *DFinally, you can specify additional IP options to be sent with every ° d ONLN d$ Æ!˙ *Fsegment. The option count is the number of long words in the IP option ° d ONLN dk$ Æ/Ï *Ffield. Pad bytes of 0 should be appended to the IP options so that the ° d ONLN d≤2 Æ= *Foptions are an integral number of long words. The maximum value of the ° d ONLN d˘@ ÆK¸ *Koption count field is 10 unless the Security flag is also nonzero, in which ° d ONLN dEN ÆY5 * case the maximum value is 9. ° d ONLN dbc Æn *KTCP does not perform any verification on the user-specified IP options, but ° d ONLN dÆq Æ|„ *Csimply inserts them into the IP header of every segment sent on the ° d ONLN dÚ Æä *Nconnection. If you specify an invalid list of IP options, the result cannot be ° d ONLN dAç Æò˛ *Epredicted. See Request for Comment (RFC) 894 for the proper format of ° d ONLN dáõ ƶ ‡ * IP options. ° d ONLN dì∞ Tª ç (◊ r Result codes ° d ONLN d†∞ ƪ … )ZnoErr ° d ONLN d¶∞5ª[ )áno error ° d ONLN dج ÆÕ ˙ (È ÃinvalidStreamPtr ° d ONLN d¿¬5Õ› )á$the specified TCP stream is not open ° d ONLN d‘ Æfl ¸ (˚ ÃconnectionExists ° d ONLN dˆ‘5fl‹ )á#this TCP stream already has an open ° d ONLN d‚5Ìh *
connection ° d ONLN d%Ù Æˇ ˜ ( ÃduplicateSocket ° d ONLN d5Ù5ˇ )á.a connection already exists between this local ° d ONLN dd5
openFailed ° d ONLN d B5Mı )á'the connection came halfway up and then ° d ONLN d4P5[O *failed , N Helvetica Narrow +Öb TCP routines
)D43 à pÃ) ˇà ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - t +<I
TCPActiveOpen , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d # 8 “ C È )-word ° d ONLN d ( 8 ˇ Cw )-csCode = TCPActiveOpen ° d ONLN d ? I x U É ( q ñÆ ° d ONLN d A J • U ± )-28 ° d ONLN d D J “ U Á )-long ° d ONLN d I J ˇ UA )-stream pointer ° d ONLN d X [ x g É ( É ñÆ ° d ONLN d Z \ • g ± )-32 ° d ONLN d ] \ “ g Ê )-byte ° d ONLN d b \ ˇ g” )--ULP timeout value in seconds; 0 = use default ° d ONLN d ê m x y É ( ï ñÆ ° d ONLN d í n • y ± )-33 ° d ONLN d ï n “ y Ê )-byte ° d ONLN d ö n ˇ yê )- ULP timeout action; 0 = report, ° d ONLN d ª | ˇ áJ *nonzero = abort ° d ONLN d À ç x ô É ( µ ñÆ ° d ONLN d Õ é • ô ± )-34 ° d ONLN d – é “ ô Ê )-byte ° d ONLN d ’ é ˇ ô4 )-
validity bits ° d ONLN d „ ü x ´ É ( « ñÆ ° d ONLN d  † • ´ ± )-36 ° d ONLN d Ë † “ ´ Á )-long ° d ONLN d Ì † ˇ ´ç )- remote IP address; cannot be 0 ° d ONLN d ± x Ω É ( Ÿ ñÆ ° d ONLN d ≤ • Ω ± )-40 ° d ONLN d ≤ “ Ω È )-word ° d ONLN d ≤ ˇ Ωà )- remote TCP port; cannot be 0 ° d ONLN d3 √ x œ É ( Î ñ¨ ° d ONLN d5 ƒ • œ ± )-42 ° d ONLN d8 ƒ “ œ Á )-long ° d ONLN d= ƒ ˇ œG )-local IP address ° d ONLN dN ’ x · É ( ˝ ñ´ ° d ONLN dP ÷ • · ± )-46 ° d ONLN dS ÷ “ · È )-word ° d ONLN dX ÷ ˇ ·Δ )-+local TCP port; if 0, TCP assigns an unused ° d ONLN dÑ ‰ ˇ Ô *port ° d ONLN dâ ı x É ( ñÆ ° d ONLN dã ˆ • ± )-48 ° d ONLN dé ˆ “ Ê )-byte ° d ONLN dì ˆ ˇB )-type of service ° d ONLN d£ x É (/ ñÆ ° d ONLN d• • ± )-49 ° d ONLN d® “ Ê )-byte ° d ONLN d≠ ˇ3 )-
precedence ° d ONLN d∏ x% É (A ñÆ ° d ONLN d∫ •% ± )-50 ° d ONLN dΩ “% Ê )-byte ° d ONLN d¬ ˇ%[ )-don’t fragment flag ° d ONLN d÷+ x7 É (S ñÆ ° d ONLN dÿ, •7 ± )-51 ° d ONLN d€, “7 Ê )-byte ° d ONLN d‡, ˇ72 )- time to live ° d ONLN dÌ= xI É (e ñÆ ° d ONLN dÔ> •I ± )-52 ° d ONLN dÚ> “I Ê )-byte ° d ONLN d˜> ˇI8 )-
security flag ° d ONLN dO x[ É (w ñÆ ° d ONLN dP •[ ± )-53 ° d ONLN d
P “[ Ê )-byte ° d ONLN dP ˇ[G )-IP option count ° d ONLN d a xm É (â ñÆ ° d ONLN d!b •m ± )-54 ° d ONLN d$b “m ˙ )-byte[40] ° d ONLN d-b ˇm. )-
IP options ° d ONLN d8s x É (õ ñÆ ° d ONLN d:t • ± )-94 ° d ONLN d=t “ Á )-long ° d ONLN dBt ˇL )-user data pointer ° d ONLN dTâ xîÕ (∞ ñETCPActiveOpen initiates an outgoing call to a remote TCP. The command ° d ONLN döó x¢æ *Fis completed when a connection is established or when an error occurs. ° d ONLN d‚¨ x∑≈ *CTCPActiveOpen accepts the same parameters as TCPPassiveOpen, except ° d ONLN d&∫ x≈– *Jthat the remote IP address and remote TCP port must be specified. Further, ° d ONLN dq» x” *Gno command timeout is provided; if the connection cannot be established ° d ONLN dπ÷ x·Æ *Awithin the ULP timeout period, the command is completed in error. ° d ONLN d˚Î xˆá *9See TCPPassiveOpen for a description of other parameters. ° d ONLN d5 W (' < Result codes ° d ONLN dB x ì )ZnoErr ° d ONLN dH ˇ % )áno error ° d ONLN dQ x ƒ (9 ñinvalidStreamPtr ° d ONLN db ˇ ß )á$the specified TCP stream is not open ° d ONLN dá$ x/ Δ (K ñconnectionExists ° d ONLN dò$ ˇ/¶ )á#this TCP stream already has an open ° d ONLN dº2 ˇ=2 *
connection ° d ONLN d«D xO ¡ (k ñduplicateSocket ° d ONLN d◊D ˇOœ )á.a connection already exists between this local ° d ONLN dR ˇ]¬ **IP address and TCP port, and the specified ° d ONLN d1` ˇkí * remote IP address and TCP port ° d ONLN dPr x} ´ (ô ñ
openFailed ° d ONLN d[r ˇ}ø )á'the connection came halfway up and then ° d ONLN dÉÄ ˇã *failed
° d ONLN d 8 T C † *Parameter block , Symbol ° d ONLN d 7 Æ C π )ZÆ ° d ONLN d 8 € C Á )-26 ° d ONLN d 8 C )-word ° d ONLN d " 85 Cé )-csCode = TCPSend ° d ONLN d 3 I Æ U π ( q ÃÆ ° d ONLN d 5 J € U Á )-28 ° d ONLN d 8 J U )-long ° d ONLN d = J5 Uw )-stream pointer ° d ONLN d L [ Æ g π ( É ÃÆ ° d ONLN d N \ € g Á )-32 ° d ONLN d Q \ g )-byte ° d ONLN d V \5 gæ )- ULP timeout value in seconds ° d ONLN d s m Æ y π ( ï ÃÆ ° d ONLN d u n € y Á )-33 ° d ONLN d x n y )-byte ° d ONLN d } n5 y‚ )-$ULP timeout action; nonzero = abort, ° d ONLN d £ |5 ád *
0 = report ° d ONLN d Æ ç Æ ô π ( µ ÃÆ ° d ONLN d ∞ é € ô Á )-34 ° d ONLN d ≥ é ô )-byte ° d ONLN d ∏ é5 ôj )-
validity bits ° d ONLN d Δ ü Æ ´ π ( « ÃÆ ° d ONLN d » † € ´ Á )-35 ° d ONLN d À † ´ )-byte ° d ONLN d – †5 ´` )- push flag ° d ONLN d ⁄ ± Æ Ω π ( Ÿ ÃÆ ° d ONLN d ‹ ≤ € Ω Á )-36 ° d ONLN d fl ≤ Ω )-byte ° d ONLN d ‰ ≤5 Ωh )- urgent flag ° d ONLN d √ Æ œ π ( Î ÃÆ ° d ONLN d Ú ƒ € œ Á )-38 ° d ONLN d ı ƒ œ )-long ° d ONLN d ˙ ƒ5 œp )- WDS pointer ° d ONLN d ’ Æ · π ( ˝ ÃÆ ° d ONLN d ÷ € · Á )-42 ° d ONLN d ÷ · )-long ° d ONLN d ÷5 ·[ )-reserved ° d ONLN d Á Æ Û π ( ÃÆ ° d ONLN d Ë € Û Á )-46 ° d ONLN d Ë Û )-word ° d ONLN d# Ë5 Û[ )-reserved ° d ONLN d, ˘ Æ π (! ÃÆ ° d ONLN d. ˙ € Á )-48 ° d ONLN d1 ˙ )-long ° d ONLN d6 ˙5Ç )-user data pointer ° d ONLN dH Æ˘ (6 ÃDTCPSend sends the specified data over the connection. The command is ° d ONLN dç Æ( *Gcompleted when all data has been sent and acknowledged or when an error ° d ONLN d’+ Æ6 œ *occurs. ° d ONLN d›@ ÆK *JIf all data cannot be sent and acknowledged within the ULP timeout period, ° d ONLN d(N ÆY˛ *Kthen the ULP action is taken. If the ULP action is abort, the connection is ° d ONLN dt\ Æg *Jbroken, all pending commands are returned, and a terminate notification is ° d ONLN døj ÆuÔ *Hgiven. If the ULP action is report, a ULP timeout notification is given. ° d ONLN d Æä˝ *FSeveral fields in the TCPPassiveOpen command are optional. To indicate ° d ONLN dOç Æò *Owhether the user is including these optional parameters, a set of validity bits ° d ONLN düõ ƶ *is defined as follows: ° d ONLN d∂≠ Æ∏ √ *bit 6 ° d ONLN dº≠∏∂ )Z%ULP timeout action parameter is valid ° d ONLN d‚ø Æ √ (Ê Ãbit 7 ° d ONLN dËø ≤ )Z$ULP timeout value parameter is valid ° d ONLN d
‘ Æfl (˚ ÃKIf the Push flag is nonzero, TCP sends the data immediately without waiting ° d ONLN dY‚ ÆÌ *Hto see if more TCPSend commands are issued. If the Urgent flag is 2, TCP ° d ONLN d¢ Æ˚¸ *Esends the data using the noncompliant method described by RFC 793. If ° d ONLN d˲ Æ ˙ *Hthe Urgent flag is any other nonzero value, TCP sends the data using the ° d ONLN d1 ÆÒ *@method described by RFC 1122. For more information about the TCP ° d ONLN dr Æ%Ó *Durgent mechanism, refer to the section “Urgent Mode” earlier in this ° d ONLN d∑( Æ3 ” *chapter. ° d ONLN d¿= ÆH *LThe WDS can be arbitrarily complex; that is, there is no limit to the number ° d ONLN d
K ÆVÒ *Dof buffers that can be sent in a TCPSend command. However, the total ° d ONLN dRY Æd
*Gnumber of data bytes described by the WDS must be between 1 and 65,535, ° d ONLN dög Ær *Einclusive. You must not modify or relocate the WDS and the buffers it ° d ONLN d‡u ÆÄ¡ *7describes until the TCPSend command has been completed. (Ÿÿ TCP routines
)D45 à pÃ) ˇÃ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! , W +<H Result codes ° d ONLN d
! x , ì )ZnoErr ° d ONLN d ! ˇ ,% )áno error ° d ONLN d 3 x > ƒ ( Z ñinvalidStreamPtr ° d ONLN d - 3 ˇ >ß )á$the specified TCP stream is not open ° d ONLN d R E x P ∏ ( l ñ
invalidLength ° d ONLN d ` E ˇ Pº )á)the total amount of data described by the ° d ONLN d ä S ˇ ^‘ *-WDS was either 0 or greater than 65,535 bytes ° d ONLN d ∏ e x p Æ ( å ñ
invalidWDS ° d ONLN d √ e ˇ pg )áthe WDS pointer was 0 ° d ONLN d Ÿ w x Ç ‚ ( û ñconnectionDoesntExist ° d ONLN d Ô w ˇ Ç∏ )á'there is no open connection on this TCP ° d ONLN d Ö ˇ ê *stream ° d ONLN d ó x ¢ Œ ( æ ñconnectionClosing ° d ONLN d0 ó ˇ ¢À )á)a TCPClose command was already issued, so ° d ONLN dZ • ˇ ∞¶ *%there is no more data to send on this ° d ONLN dÄ ≥ ˇ æ2 *
connection ° d ONLN dã ≈ x – ‡ ( Ï ñconnectionTerminated ° d ONLN d† ≈ ˇ –– )á-the connection was broken; the reason will be ° d ONLN dŒ ” ˇ fir *given in a terminate ASR , N Helvetica Narrow
8 T C † *Parameter block , Symbol ° d ONLN d 7 Æ C π )ZÆ ° d ONLN d 8 € C Á )-26 ° d ONLN d " 8 C )-word ° d ONLN d ' 85 CØ )-csCode = TCPNoCopyRcv ° d ONLN d = I Æ U π ( q ÃÆ ° d ONLN d ? J € U Á )-28 ° d ONLN d B J U )-long ° d ONLN d G J5 Uw )-stream pointer ° d ONLN d V [ Æ g π ( É ÃÆ ° d ONLN d X \ € g Á )-32 ° d ONLN d [ \ g )-byte ° d ONLN d ` \5 gº )-command timeout in seconds ° d ONLN d { m Æ y π ( ï è ° d ONLN d } n € y Á )-34 ° d ONLN d Ä n y )-byte ° d ONLN d Ö n5 yb )- mark flag ° d ONLN d è Æ ã π ( ß Ã¨ ° d ONLN d ë Ä € ã Á )-35 ° d ONLN d î Ä ã )-byte ° d ONLN d ô Ä5 ãh )- urgent flag ° d ONLN d • ë Æ ù π ( π ÃÆ ° d ONLN d ß í € ù Á )-42 ° d ONLN d ™ í ù )-long ° d ONLN d Ø í5 ùÊ )-#RDS pointer; RDS is modified by TCP ° d ONLN d ” £ Æ Ø π ( À ÃÆ ° d ONLN d ’ § € Ø Á )-46 ° d ONLN d ÿ § Ø )-word ° d ONLN d › §5 Ø‹ )-"number of entries in RDS excluding ° d ONLN d ≤5 Ω€ *"terminating 0; not modified by TCP ° d ONLN d# √ Æ œ π ( Î ÃÆ ° d ONLN d% ƒ € œ Á )-48 ° d ONLN d( ƒ œ )-word ° d ONLN d- ƒ5 œ[ )-reserved ° d ONLN d6 ’ Æ · π ( ˝ ÃÆ ° d ONLN d8 ÷ € · Á )-50 ° d ONLN d; ÷ · )-long ° d ONLN d@ ÷5 ·Ç )-user data pointer ° d ONLN dR Î Æ ˆ ( ÃHTCPNoCopyRcv retrieves data that has been received on a connection. Data ° d ONLN dõ ˘ Æ
*Mis not copied out of the internal buffers of TCP; rather, an RDS is formatted ° d ONLN dÈ ÆÚ *Fto allow the user access to the TCP data in place. This command offers ° d ONLN d0 Æ ◊ *:significant performance improvements over TCPRcv commands. ° d ONLN dk1 Æ<I * The command is completed when , p AppleIcon p
° d ONLN dâE ÆM ≥ *n
° d ONLN dãC ªN )
pushed data arrives p
° d ONLN düW Æ_ ≥ (| Ãn
° d ONLN d°U ª`2 )
urgent data is outstanding p
° d ONLN dºi Æq ≥ (é Ãn
° d ONLN dæg ªr )
Ga reasonable period passes after the arrival of nonpush, nonurgent data p
° d ONLN d{ ÆÉ ≥ († Ãn
° d ONLN dy ªÑÍ )
Dthe RDS is full; that is, the received data is in more noncontiguous ° d ONLN dMá ªíX * chunks than the RDS can describe p
° d ONLN dnõ Æ£ ≥ (¿ Ãn
° d ONLN dpô ª§ )
Ithe amount of data received is greater than or equal to 25 percent of the ° d ONLN d∫ß ª≤f *'total receive buffering for this stream p
° d ONLN d‚ª Æ√ ≥ (‡ Ãn
° d ONLN d‰π ªƒD )
the command timeout expires ° d ONLN d Œ ÆŸ˘ (ı ÃDYou must allocate memory for the RDS, which can contain an unlimited ° d ONLN dE‹ ÆÁ *Gnumber of elements. The specified number of entries in the RDS does not ° d ONLN dçÍ Æı *Iinclude the terminating 0. For example, the simplest possible RDS has one ° d ONLN d◊¯ Æ˝ *Lelement and is 8 bytes in length: a word length field, a long pointer field, ° d ONLN d$ Æj *)and a terminating word length field of 0. ° d ONLN dN Æ& *FTCP formats the RDS to point to the received TCP data. The RDS may not ° d ONLN dï) Æ4
*Kbe completely filled by TCP. For example, if you pass an RDS three entries, ° d ONLN d·7 ÆB *ATCP may complete the TCPNoCopyRcv command with the RDS describing ° d ONLN d#E ÆPı *Bonly one buffer. TCP does not modify the field in the TCPNoCopyRcv ° d ONLN dfS Æ^ *Lcommand that indicates the number of entries in the RDS; rather, it places a ° d ONLN d≥a ÆlK *#terminating zero in the RDS itself. (Ÿÿ TCP routines
)D47 Ã pÃ) ˇ
◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x ,« +ñHEThe command timeout period starts when the receive command is issued, ° d ONLN d F / x :œ *Onot when the first byte of data arrives. If no data arrives within this timeout ° d ONLN d ñ = x HÀ *Dperiod, the TCPNoCopyRcv command is completed in error. If some data ° d ONLN d € K x V≥ *>has arrived when the command timeout expires, the TCPNoCopyRcv ° d ONLN d Y x d *Icommand is completed successfully, returning the data that has arrived so ° d ONLN dd g x r« *Ifar. A command timeout of 0 indicates an infinite timeout period. In this ° d ONLN dÆ u x Ä» *Ccase, the TCPNoCopyRcv command is not completed until some data has ° d ONLN dÚ É x é õ *arrived. ° d ONLN d˚ ò x £Ω *GIf the Urgent flag is nonzero, the data returned by this command is the ° d ONLN dC ¶ x ±¢ *Abeginning of the outstanding urgent data. This flag is one of two ° d ONLN dÖ ¥ x øº *Bmechanisms that puts you in urgent mode. The other mechanism is by ° d ONLN d» ¬ x Õ∏ *Dmeans of an urgent ASR notification, which is used when there are no ° d ONLN d
– x €j *,outstanding TCPNoCopyRcv or TCPRcv commands. ° d ONLN d:  x ƒ *GIf the Mark flag is nonzero, the data returned by this command ends the ° d ONLN dÇ Û x ˛¨ *Aurgent data. Since TCP does not deliver urgent and nonurgent data ° d ONLN dƒ x µ *Htogether, the last byte of data described by the RDS is the last byte of ° d ONLN d
! Æ , … )ZnoErr ° d ONLN d !5 ,[ )áno error ° d ONLN d 3 Æ > ˙ ( Z ÃinvalidStreamPtr ° d ONLN d - 35 >› )á$the specified TCP stream is not open ° d ONLN d R E Æ P ( l ÃconnectionDoesntExist ° d ONLN d h E5 PÓ )á&this TCP stream has no open connection ° d ONLN d è W Æ b Ó ( ~ Ã
invalidLength ° d ONLN d ù W5 bó )áthe RDS has 0 entries ° d ONLN d ≥ i Æ t Î ( ê Ã
° d ONLN dà T † *Parameter block , Symbol ° d ONLN d‹ Æ π )ZÆ ° d ONLN dfi € Á )-26 ° d ONLN d· )-word ° d ONLN dÊ5∂ )-csCode = TCPRcvBfrReturn ° d ONLN dˇ Æ% π (A ÃÆ ° d ONLN d €% Á )-28 ° d ONLN d% )-long ° d ONLN d 5%w )-stream pointer ° d ONLN d+ Æ7 π (S ÃÆ ° d ONLN d, €7 Á )-42 ° d ONLN d ,7 )-long ° d ONLN d",57n )- RDS pointer ° d ONLN d.= ÆI π (e ÃÆ ° d ONLN d0> €I Á )-50 ° d ONLN d3>I )-long ° d ONLN d8>5IÇ )-user data pointer ° d ONLN dJS Æ^Ï (z ÃFTCPBfrReturn returns to the TCP driver a set of receive buffers that a ° d ONLN dëa Æl¸ *Bsuccessfully completed TCPNoCopyRcv command passed directly to the ° d ONLN d‘o ÆzÚ *Euser. The RDS must be identical to the RDS given to the user when the ° d ONLN d} Æà *CTCPNoCopyRcv command is completed. TCPBfrReturn returns an error if ° d ONLN d^ã Æñ¶ *6you attempt to return a set of buffers more than once. ° d ONLN dï† T´ ç (« r Result codes ° d ONLN d¢† Æ´ … )ZnoErr ° d ONLN d®†5´[ )áno error ° d ONLN d±≤ ÆΩ ˙ (Ÿ ÃinvalidStreamPtr ° d ONLN d¬≤5Ω› )á$the specified TCP stream is not open ° d ONLN dÁƒ Æœ (Î ÃconnectionDoesntExist ° d ONLN d˝ƒ5œÓ )á&this TCP stream has no open connection ° d ONLN d$÷ Æ· Î (˝ Ã
invalidBufPtr ° d ONLN d2÷5·õ )áthe RDS pointer was 0 ° d ONLN dHË ÆÛ ‚ ( Ã
invalidRDS ° d ONLN dSË5Û˛ )á+the RDS refers to receive buffers not owned ° d ONLN dˆ5h * by the user +Öº TCP routines
)D49 à pÃ) ˇÍ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - J +<ITCPRcv , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d ! 8 ˇ CR )-csCode = TCPRcv ° d ONLN d 1 I x U É ( q ñÆ ° d ONLN d 3 J • U ± )-28 ° d ONLN d 6 J “ U Á )-long ° d ONLN d ; J ˇ UA )-stream pointer ° d ONLN d J [ x g É ( É ñÆ ° d ONLN d L \ • g ± )-32 ° d ONLN d O \ “ g Ê )-byte ° d ONLN d T \ ˇ gÜ )-command timeout in seconds ° d ONLN d o m x y É ( ï ñ¨ ° d ONLN d q n • y ± )-34 ° d ONLN d t n “ y Ê )-byte ° d ONLN d y n ˇ y, )- mark flag ° d ONLN d É x ã É ( ß ñ¨ ° d ONLN d Ö Ä • ã ± )-35 ° d ONLN d à Ä “ ã Ê )-byte ° d ONLN d ç Ä ˇ ã2 )- urgent flag ° d ONLN d ô ë x ù É ( π ñÆ ° d ONLN d õ í • ù ± )-36 ° d ONLN d û í “ ù Á )-long ° d ONLN d £ í ˇ ùc )-receive buffer pointer ° d ONLN d ∫ £ x Ø É ( À ñ´ ° d ONLN d º § • Ø ± )-40 ° d ONLN d ø § “ Ø È )-word ° d ONLN d ƒ § ˇ Ø_ )-receive buffer length ° d ONLN d ⁄ µ x ¡ É ( › ñÆ ° d ONLN d ‹ ∂ • ¡ ± )-48 ° d ONLN d fl ∂ “ ¡ È )-word ° d ONLN d ‰ ∂ ˇ ¡% )-reserved ° d ONLN d Ì « x ” É ( Ô ñÆ ° d ONLN d Ô » • ” ± )-50 ° d ONLN d Ú » “ ” Á )-long ° d ONLN d ˜ » ˇ ”L )-user data pointer ° d ONLN d › x Ë∂ ( ñETCPRcv retrieves data that has been received on a connection. Data is ° d ONLN dO Î x ˆ• *Bcopied out of the TCP internal buffers into the user’s buffer. The ° d ONLN dí ˘ x ˛ *command is completed when , p AppleIcon p
° d ONLN d¨
x } *n
° d ONLN dÆ Öc )
2enough data has arrived to fill the receive buffer p
° d ONLN d· x' } (D ñn
° d ONLN d„ Ö( › )
pushed data arrives p
° d ONLN d˜1 x9 } (V ñn
° d ONLN d˘/ Ö: ¸ )
urgent data is outstanding p
° d ONLN dC xK } (h ñn
° d ONLN dA ÖLø )
Da reasonable period passes after the arrival of nonpushed, nonurgent ° d ONLN d[O ÖZ ò *data p
° d ONLN d`c xk } (à ñn
° d ONLN dba Öl– )
Ithe amount of data received is greater than or equal to 25 percent of the ° d ONLN d¨o Öz0 *'total receive buffering for this stream p
Ω *GIf the Urgent flag is nonzero, the data returned by this command is the ° d ONLN d‡
x¢ *Abeginning of the outstanding urgent data. This flag is one of two ° d ONLN d" x&º *Bmechanisms that puts you in urgent mode. The other mechanism is by ° d ONLN de) x4∏ *Dmeans of an urgent ASR notification, which is used when there are no ° d ONLN d™7 xBj *,outstanding TCPNoCopyRcv or TCPRcv commands. ° d ONLN d◊L xWƒ *GIf the Mark flag is nonzero, the data returned by this command ends the ° d ONLN d Z xe¨ *Aurgent data. Since TCP does not deliver urgent and nonurgent data ° d ONLN dah xsœ *Ptogether, the last byte of data in the receive buffer is the last byte of urgent ° d ONLN d≤v xŃ *Fdata. The Mark flag is the only mechanism for taking you out of urgent ° d ONLN d˘Ñ xè ï *mode.
(Ÿ <50
))Chapter 4 / Transmission Control Protocol à :ÃÛ ˇ
invalidLength ° d ONLN d∂u5Ĭ )á the receive buffer length was 0 ° d ONLN d÷á Æí Î (Æ Ã
invalidBufPtr ° d ONLN d‰á5íΔ )á the receive buffer pointer was 0 ° d ONLN dô Ƨ (¿ ÃcommandTimeout ° d ONLN dô5§¸ )á,no data arrived within the specified timeout ° d ONLN dAß5≤S *period ° d ONLN dHπ ƃ (‡ ÃconnectionDoesntExist ° d ONLN d^π5ƒÓ )á&this TCP stream has no open connection ° d ONLN dÖÀ Æ÷ (Ú ÃconnectionClosing ° d ONLN dóÀ5÷˛ )á,all data on this connection has already been ° d ONLN dƒŸ5‰_ * delivered ° d ONLN dŒÎ ƈ ( ÃconnectionTerminated ° d ONLN d„Î5ˆ )á-the connection was broken; the reason will be ° d ONLN d˘5® *given in a terminate ASR , N Helvetica Narrow +Öπ TCP routines
)F51 Ã pÃ) ˇ
® ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - S +<ITCPClose , Times
° d ONLN d 8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d # 8 ˇ CZ )-csCode = TCPClose ° d ONLN d 5 I x U É ( q ñÆ ° d ONLN d 7 J • U ± )-28 ° d ONLN d : J “ U Á )-long ° d ONLN d ? J ˇ UA )-stream pointer ° d ONLN d N [ x g É ( É ñÆ ° d ONLN d P \ • g ± )-32 ° d ONLN d S \ “ g Ê )-byte ° d ONLN d X \ ˇ gà )- ULP timeout value in seconds ° d ONLN d u m x y É ( ï ñÆ ° d ONLN d w n • y ± )-33 ° d ONLN d z n “ y Ê )-byte ° d ONLN d n ˇ yê )- ULP timeout action; 0 = report, ° d ONLN d † | ˇ áJ *nonzero = abort ° d ONLN d ∞ ç x ô É ( µ ñÆ ° d ONLN d ≤ é • ô ± )-34 ° d ONLN d µ é “ ô Ê )-byte ° d ONLN d ∫ é ˇ ô4 )-
validity bits ° d ONLN d » ü x ´ É ( « ñÆ ° d ONLN d † • ´ ± )-35 ° d ONLN d Õ † “ ´ Á )-long ° d ONLN d “ † ˇ ´L )-user data pointer ° d ONLN d ‰ µ x ¿— ( ‹ ñJTCPClose signals that the user has no more data to send on the connection. ° d ONLN d/ √ x ŒΔ *EIt does not mean that the connection should be broken. The remote TCP ° d ONLN du — x ‹– *Lmust also issue a close before the connection can be gracefully closed, so a ° d ONLN d¬ fl x Í‘ *Iconnection may remain an arbitrary amount of time after you have issued a ° d ONLN d Ì x ¯Δ *GTCPClose. To break a connection without ensuring that all data has been ° d ONLN dT ˚ xπ *Asent and acknowledged, use the TCPAbort command. (See the section ° d ONLN dñ xN *.“Connection Closing” earlier in this chapter.) ° d ONLN d≈ x)¢ *<The command is completed when the FIN flag has been sent and ° d ONLN d, x7Ω *Cacknowledged. If the FIN is not acknowledged within the ULP timeout ° d ONLN dF: xE∫ *Hperiod, the ULP timeout action is taken. If the ULP action is abort, the ° d ONLN dèH xSŒ *Hconnection is broken, all pending commands are returned, and a terminate ° d ONLN dÿV xa“ *Nnotification is given. If the ULP action is report, a ULP timeout notification ° d ONLN d'd xo û * is given. ° d ONLN d1y xÑ« *FSeveral fields in the TCPPassiveOpen command are optional. To indicate ° d ONLN dxá xí“ *Owhether the user is including these optional parameters, a set of validity bits ° d ONLN d»ï x† ÿ *is defined as follows: ° d ONLN dflß x≤ ç *bit 6 ° d ONLN dÂß “≤Ä )Z%ULP timeout action parameter is valid ° d ONLN d π xƒ ç (‡ ñbit 7 ° d ONLN d𠓃| )Z$ULP timeout value parameter is valid ° d ONLN d6Œ Ÿ W (ı < Result codes ° d ONLN dCŒ xŸ ì )ZnoErr ° d ONLN dIŒ ˇŸ% )áno error ° d ONLN dR‡ xÎ ƒ ( ñinvalidStreamPtr ° d ONLN dc‡ ˇÎß )á$the specified TCP stream is not open ° d ONLN dàÚ x˝ ‚ ( ñconnectionDoesntExist ° d ONLN dûÚ ˇ˝∏ )á&this TCP stream has no open connection ° d ONLN d≈ x Œ (+ ñconnectionClosing ° d ONLN d◊ ˇ» )á'one TCPClose command was already issued ° d ONLN dˇ ˇ V *for this connection ° d ONLN d$ x/ ‡ (K ñconnectionTerminated ° d ONLN d($ ˇ/– )á-the connection was broken; the reason will be ° d ONLN dV2 ˇ=r *given in a terminate ASR
8 C j *Parameter block , Symbol ° d ONLN d 7 x C É )ZÆ ° d ONLN d 8 • C ± )-26 ° d ONLN d 8 “ C È )-word ° d ONLN d $ 8 ˇ C\ )-csCode = TCPStatus ° d ONLN d 7 I x U É ( q ñÆ ° d ONLN d 9 J • U ± )-28 ° d ONLN d < J “ U Á )-long ° d ONLN d A J ˇ UA )-stream pointer ° d ONLN d P [ x g É ( É ñ¨ ° d ONLN d R \ • g ± )-32 ° d ONLN d U \ “ g Ê )-byte ° d ONLN d Z \ ˇ gà )- ULP timeout value in seconds ° d ONLN d w m x y É ( ï ñ¨ ° d ONLN d y n • y ± )-33 ° d ONLN d | n “ y Ê )-byte ° d ONLN d Å n ˇ yê )- ULP timeout action; 0 = report, ° d ONLN d ¢ | ˇ áJ *nonzero = abort ° d ONLN d ≤ ç x ô É ( µ ñ¨ ° d ONLN d ¥ é • ô ± )-38 ° d ONLN d ∑ é “ ô Á )-long ° d ONLN d º é ˇ ôQ )-remote IP address ° d ONLN d Œ ü x ´ É ( « ñ¨ ° d ONLN d – † • ´ ± )-42 ° d ONLN d ” † “ ´ È )-word ° d ONLN d ÿ † ˇ ´L )-remote TCP port ° d ONLN d Ë ± x Ω É ( Ÿ ñ¨ ° d ONLN d Í ≤ • Ω ± )-44 ° d ONLN d Ì ≤ “ Ω Á )-long ° d ONLN d Ú ≤ ˇ ΩG )-local IP address ° d ONLN d √ x œ É ( Î ñ¨ ° d ONLN d ƒ • œ ± )-48 ° d ONLN d ƒ “ œ È )-word ° d ONLN d
ƒ ˇ œB )-local TCP port ° d ONLN d ’ x · É ( ˝ ñ¨ ° d ONLN d ÷ • · ± )-50 ° d ONLN d! ÷ “ · Ê )-byte ° d ONLN d& ÷ ˇ ·B )-type of service ° d ONLN d6 Á x Û É ( ñ¨ ° d ONLN d8 Ë • Û ± )-51 ° d ONLN d; Ë “ Û Ê )-byte ° d ONLN d@ Ë ˇ Û3 )-
precedence ° d ONLN dK ˘ x É (! ñ¨ ° d ONLN dM ˙ • ± )-52 ° d ONLN dP ˙ “ Ê )-byte ° d ONLN dU ˙ ˇ` )-TCP connection state ° d ONLN dj x É (3 ñ¨ ° d ONLN dl • ± )-54 ° d ONLN do “ È )-word ° d ONLN dt ˇ: )- send window ° d ONLN dÄ x) É (E ñ¨ ° d ONLN dÇ •) ± )-56 ° d ONLN dÖ “) È )-word ° d ONLN dä ˇ)E )-receive window ° d ONLN dô/ x; É (W ñ¨ ° d ONLN dõ0 •; ± )-58 ° d ONLN dû0 “; È )-word ° d ONLN d£0 ˇ;ñ )- amount of unacknowledged data ° d ONLN d¡A xM É (i ñ¨ ° d ONLN d√B •M ± )-60 ° d ONLN dΔB “M È )-word ° d ONLN dÀB ˇMh )-amount of unread data ° d ONLN d·S x_ É ({ ñ¨ ° d ONLN d„T •_ ± )-62 ° d ONLN dÊT “_ Á )-long ° d ONLN dÎT ˇ_h )-security option pointer ° d ONLN de xq É (ç ñ¨ ° d ONLN df •q ± )-66 ° d ONLN df “q Á )-long ° d ONLN d
f ˇqe )-send unacknowledged ° d ONLN d!w xÉ É (ü ñ¨ ° d ONLN d#x •É ± )-70 ° d ONLN d&x “É Á )-long ° d ONLN d+x ˇÉ+ )- send next ° d ONLN d5â xï É (± ñ¨ ° d ONLN d7ä •ï ± )-74 ° d ONLN d:ä “ï Á )-long ° d ONLN d?ä ˇïW )-congestion window ° d ONLN dQõ xß É (√ ñ¨ ° d ONLN dSú •ß ± )-78 ° d ONLN dVú “ß Á )-long ° d ONLN d[ú ˇß6 )- receive next ° d ONLN dh≠ xπ É (’ ñ¨ ° d ONLN djÆ •π ± )-82 ° d ONLN dmÆ “π Á )-long ° d ONLN drÆ ˇπæ )-(smoothed round-trip time in milliseconds ° d ONLN dõø xÀ É (Á ñ¨ ° d ONLN dù¿ •À ± )-86 ° d ONLN d†¿ “À Á )-long ° d ONLN d•¿ ˇÀ† )-$last round-trip time in milliseconds ° d ONLN d — x› É (˘ ñ¨ ° d ONLN dÓ •› ± )-90 ° d ONLN dœ“ “› Á )-long ° d ONLN d‘“ ˇ›µ )-%maximum segment size that can be sent ° d ONLN d˙„ xÔ É ( ñ¨ ° d ONLN d¸‰ •Ô ± )-94 ° d ONLN dˇ‰ “Ô Á )-long ° d ONLN d‰ ˇÔq )-pointer to statistics block ° d ONLN d ı x É ( ñÆ ° d ONLN d"ˆ • ± )-98 ° d ONLN d%ˆ “ Á )-long ° d ONLN d*ˆ ˇL )-user data pointer ° d ONLN d< x¨ (2 ñ@TCPStatus allows you to extract information from TCP regarding a ° d ONLN d} x$ › *particular connection. ° d ONLN dî. x9º *BSee the TCPPassiveOpen command for a description of the usual open ° d ONLN d◊< xG Ò *parameters (bytes 32–51). ° d ONLN dÒX xcb * 2The TCP connection state has the following values: ° d ONLN d$j xu ~ *0 ° d ONLN d&j •u ƒ )-Closed ° d ONLN d-j ˇu† )Z#no connection exists on this stream ° d ONLN dQ| xá ~ (£ ñ2 ° d ONLN dS| •á ¡ )-Listen ° d ONLN dZ| ˇá™ )Z$listening for an incoming connection
. ° d ONLN d ! Æ , ¥ +ÃH4 ° d ONLN d ! € , )- SYN received ° d ONLN d !5 ,Û )Z(incoming connection is being established ° d ONLN d 8 3 Æ > ¥ ( Z Ã6 ° d ONLN d : 3 € > )-SYN sent ° d ONLN d C 35 >Ò )Z(outgoing connection is being established ° d ONLN d l E Æ P ¥ ( l Ã8 ° d ONLN d n E € P )- Established ° d ONLN d z E5 PÅ )Zconnection is up ° d ONLN d ã W Æ b ∫ ( ~ Ã10 ° d ONLN d é W € b
)-
FIN Wait 1 ° d ONLN d ô W5 bË )Z'connection is up; close has been issued ° d ONLN d ¡ i Æ t ∫ ( ê Ã12 ° d ONLN d ƒ i € t
)-
FIN Wait 2 ° d ONLN d œ i5 t¸ )Z*connection is up; close has been completed ° d ONLN d ˙ { Æ Ü ∫ ( ¢ Ã14 ° d ONLN d ˝ { € Ü )-
Close Wait ° d ONLN d {5 ÜÚ )Z)connection is up; close has been received ° d ONLN d2 ç Æ ò ∫ ( ¥ Ã16 ° d ONLN d5 ç € ò ˛ )-Closing ° d ONLN d= ç5 òˇ )Z,connection is up; close has been issued and ° d ONLN dk õ5 ¶[ *received ° d ONLN dt ≠ Æ ∏ ∫ ( ‘ Ã18 ° d ONLN dw ≠ € ∏ )-Last Ack ° d ONLN dÄ ≠5 ∏ˇ )Z,connection is up; close has been issued and ° d ONLN dÆ ª5 Δ[ *received ° d ONLN d∑ Õ Æ ÿ ∫ ( Ù Ã20 ° d ONLN d∫ Õ € ÿ
)- Time Wait ° d ONLN dƒ Õ5 ÿ≥ )Zconnection is being broken ° d ONLN dfl ‚ Æ Ì ( ÃIThe send window is the amount of data the remote TCP is currently willing ° d ONLN d) Æ ˚ *Jto accept from the local TCP. The receive window is the amount of data the ° d ONLN dt ˛ Æ » *=local TCP is currently willing to accept from the remote TCP. ° d ONLN d≤ Æ%Ö * 1The statistics block has the following structure: ° d ONLN d‰, Æ7 ¥ *0 ° d ONLN dÊ, €7 )-long ° d ONLN dÎ,57“ )Z number of data segments received ° d ONLN d > ÆI ¥ (e Ã4 ° d ONLN d> €I )-long ° d ONLN d>5Iæ )Z number of data segments sent ° d ONLN d0P Æ[ ¥ (w Ã8 ° d ONLN d2P €[ )-long ° d ONLN d7P5[Ë )Z%number of data segments retransmitted ° d ONLN d]b Æm ∫ (â Ã12 ° d ONLN d`b €m )-long ° d ONLN deb5m¿ )Z number of data bytes received ° d ONLN dÉt Æ ∫ (õ Ã16 ° d ONLN dÜt € )-long ° d ONLN dãt5Ì )Z'number of duplicate data bytes received ° d ONLN d≥Ü Æë ∫ (≠ Ã20 ° d ONLN d∂Ü €ë )-long ° d ONLN dªÜ5ë )Z,number of data bytes received beyond receive ° d ONLN dËî5üX *window ° d ONLN dÔ¶ Ʊ ∫ (Õ Ã24 ° d ONLN dÚ¶ €± )-long ° d ONLN d˜¶5±¨ )Znumber of data bytes sent ° d ONLN d∏ Æ√ ∫ (fl Ã28 ° d ONLN d∏ €√ )-long ° d ONLN d∏5√÷ )Z"number of data bytes retransmitted ° d ONLN d< Æ’ ∫ (Ò Ã32 ° d ONLN d? €’ Ù )-struct ° d ONLN dF 5’Δ )Z size histogram of sent segments ° d ONLN dfÊ ÆÒË (
ÃEThe histogram is a variable-length structure of the following format: ° d ONLN d¨¯ Æ ¥ *0 ° d ONLN dƯ € Ú )-word ° d ONLN d≥¯5† )Znumber of size buckets ° d ONLN d
Æ ¥ (1 Ã2 ° d ONLN dÃ
€ Ú )-word ° d ONLN d—
5¥ )Z value: smallest segment size ° d ONLN dÓ Æ' ¥ (C Ã4 ° d ONLN d €' )-long ° d ONLN dı 5'¯ )Z'counter number: number of segments sent ° d ONLN d *55Ô **between this size and the next larger size ° d ONLN dH< ÆG ¥ (c Ã8 ° d ONLN dJ< €G Ú )-word ° d ONLN dO<5G◊ )Z#value: second smallest segment size ° d ONLN dsN ÆY ∫ (u Ã10 ° d ONLN dvN €Y )-long ° d ONLN d{N5Y¯ )Z'counter number: number of segments sent ° d ONLN d£\5gÔ **between this size and the next larger size , N Helvetica Narrow +ÖV TCP routines
)E55 à pÃ) ˇ ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x ,™ +ñHEYou are free to update the statistics block. Only the counters in the ° d ONLN d F / x :« *Esegment-size histogram should be modified. The number of size buckets ° d ONLN d å = x Hõ *=and the segment-size value for each bucket cannot be changed. ° d ONLN d R ] W ( y < Result codes ° d ONLN d ◊ R x ] ì )ZnoErr ° d ONLN d › R ˇ ]% )áno error ° d ONLN d Ê d x o ƒ ( ã ñinvalidStreamPtr ° d ONLN d ˜ d ˇ oß )á$the specified TCP stream is not open ° d ONLN d v x Å ‚ ( ù ñconnectionDoesntExist ° d ONLN d2 v ˇ Å∏ )á&this TCP stream has no open connection , N Helvetica Narrow
° d ONLN dY ú ™ _ ( Δ <
TCPRelease
° d ONLN dd µ ¿ j *Parameter block , Symbol ° d ONLN dt ¥ x ¿ É )ZÆ ° d ONLN dv µ • ¿ ± )-26 ° d ONLN dy µ “ ¿ È )-word ° d ONLN d~ µ ˇ ¿c )-csCode = TCPRelease ° d ONLN dí Δ x “ É ( Ó ñÆ ° d ONLN dî « • “ ± )-28 ° d ONLN dó « “ “ Á )-long ° d ONLN dú « ˇ “A )-stream pointer ° d ONLN d´ ÿ x ‰ É ( ñ¨ ° d ONLN d≠ Ÿ • ‰ ± )-32 ° d ONLN d∞ Ÿ “ ‰ Á )-long ° d ONLN dµ Ÿ ˇ ‰Ö )- pointer to receive buffer area ° d ONLN d‘ Í x ˆ É ( ñ¨ ° d ONLN d÷ Î • ˆ ± )-36 ° d ONLN dŸ Î “ ˆ Á )-long ° d ONLN dfi Î ˇ ˆÇ )- length of receive buffer area ° d ONLN d¸ ¸ x É ($ ñÆ ° d ONLN d˛ ˝ • ± )-44 ° d ONLN d ˝ “ Á )-long ° d ONLN d ˝ ˇL )-user data pointer ° d ONLN d x º (9 ñETCPRelease closes a TCP stream. If there is an open connection on the ° d ONLN d^ x+— *Gstream, the connection is first broken as though a TCPAbort command had ° d ONLN d¶. x9 ∞ * been issued. ° d ONLN d≥C xNŒ *IThe receive buffer area passed to the MacTCP driver in the TCPCreate call ° d ONLN d˝Q x\” *Ois returned to the user. You are now free to reuse or release this buffer area. ° d ONLN dMf q W (ç < Result codes ° d ONLN dZf xq ì )ZnoErr ° d ONLN d`f ˇq% )áno error ° d ONLN dix xÉ ƒ (ü ñinvalidStreamPtr ° d ONLN dzx ˇÉß )á$the specified TCP stream is not open
° d ONLN d 8 T C † *Parameter block , Symbol ° d ONLN d 7 Æ C π )ZÆ ° d ONLN d 8 € C Á )-26 ° d ONLN d # 8 C )-word ° d ONLN d ( 85 C™ )-csCode = TCPGlobalInfo ° d ONLN d ? I Æ U π ( q è ° d ONLN d A J € U Á )-32 ° d ONLN d D J U )-long ° d ONLN d I J5 UÆ )-pointer to TCP parameters ° d ONLN d c [ Æ g π ( É Ã¨ ° d ONLN d e \ € g Á )-36 ° d ONLN d h \ g )-long ° d ONLN d m \5 g° )-pointer to TCP statistics ° d ONLN d á m Æ y π ( ï è ° d ONLN d â n € y Á )-40 ° d ONLN d å n y )-long ° d ONLN d ë n5 yî )-pointer to CDB table ° d ONLN d ¶ Æ ã π ( ß ÃÆ ° d ONLN d ® Ä € ã Á )-44 ° d ONLN d ´ Ä ã )-long ° d ONLN d ∞ Ä5 ãÇ )-user data pointer ° d ONLN d ¬ ú Æ ßö ( √ Ã.The TCPGlobalInfo command allows you access to , p AppleIcon p
° d ONLN d Ò ∞ Æ ∏ ≥ *n
° d ONLN d Û Æ ª πÇ )
+parameters that affect the operation of TCP p
° d ONLN d ¬ Æ ≥ ( Á Ãn
° d ONLN d! ¿ ª ÀR )
"global statistics collected by TCP ° d ONLN dD ‹ Æ Á› ( Ã?You should not modify the TCP parameters. The structure has the ° d ONLN dÑ Í Æ ı ˇ *following format: ° d ONLN dñ ¸ Æ ¥ *0 ° d ONLN dò ¸ € )-long ° d ONLN dù ¸È )-2pointer to Pascal string describing retransmission ° d ONLN d–
[ *timeout algorithm ° d ONLN d‚ Æ' ¥ (C Ã4 ° d ONLN d‰ €' )-long ° d ONLN dÈ 'ÿ )-+minimum value of retransmission timeout (in ° d ONLN d*5E *
milliseconds) ° d ONLN d#< ÆG ¥ (c Ã8 ° d ONLN d%< €G )-long ° d ONLN d*<G⁄ )-+maximum value of retransmission timeout (in ° d ONLN dVJUE *
milliseconds) ° d ONLN dd\ Æg ∫ (É Ã12 ° d ONLN dg\ €g )-long ° d ONLN dl\g‘ )-)maximum segment size this TCP can receive ° d ONLN dñn Æy ∫ (ï Ã16 ° d ONLN dôn €y )-long ° d ONLN dûny˝ )-/maximum number of streams the MacTCP driver can ° d ONLN dŒ|á+ *support ° d ONLN d÷é Æô ∫ (µ Ã20 ° d ONLN dŸé €ô )-long ° d ONLN dfiéô )-1maximum value of receive window the MacTCP driver ° d ONLN dúß2 * can offer ° d ONLN d± ƺı (ÿ ÃJThe TCP statistics are the sum of traffic information for all streams that ° d ONLN deø Æ *Ihave been opened since system startup time. The counters will wrap around ° d ONLN dØÕ Æÿ¸ *Dto 0 when incremented past their maximum value. You can modify these ° d ONLN dÙ€ ÆÊ ÷ * statistics. ° d ONLN d˜ Æ° * 6The TCP statistics structure has the following format: ° d ONLN d8 Æ ¥ *0 ° d ONLN d: € )-long ° d ONLN d? – )-(number of outgoing connections attempted ° d ONLN dh Æ& ¥ (B Ã4 ° d ONLN dj €& )-long ° d ONLN do&≈ )-%number of outgoing connections opened ° d ONLN dï- Æ8 ¥ (T Ã8 ° d ONLN dó- €8 )-long ° d ONLN dú-8Õ )-'number of incoming connections accepted ° d ONLN dƒ? ÆJ ∫ (f Ã12 ° d ONLN d«? €J )-long ° d ONLN dÃ?JŸ )-,number of connections that closed gracefully ° d ONLN d˘Q Æ\ ∫ (x Ã16 ° d ONLN d¸Q €\ )-long ° d ONLN dQ\≈ )-'number of connections that were aborted ° d ONLN d)c Æn ∫ (ä Ã20 ° d ONLN d,c €n )-long ° d ONLN d1cnì )- number of data bytes received ° d ONLN dOu ÆÄ ∫ (ú Ã24 ° d ONLN dRu €Ä )-long ° d ONLN dWuÄ )-number of data bytes sent ° d ONLN dqá Æí ∫ (Æ Ã28 ° d ONLN dtá €í )-long ° d ONLN dyáí¿ )-'number of duplicate data bytes received +≤+ TCP routines
)E57 à pÃ) ˇ4 ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x , Ñ +ñH32 ° d ONLN d ! • , ∫ )-long ° d ONLN d ! “ ,s )-"number of data bytes retransmitted ° d ONLN d + 3 x > Ñ ( Z ñ36 ° d ONLN d . 3 • > ∫ )-long ° d ONLN d 3 3 “ >ù )-+total number of segments received (includes ° d ONLN d _ A “ L( *acknowledgments) ° d ONLN d p S x ^ Ñ ( z ñ40 ° d ONLN d s S • ^ ∫ )-long ° d ONLN d x S “ ^â )-'total number of segments sent (includes ° d ONLN d † a “ l( *acknowledgments) ° d ONLN d ± s x ~ Ñ ( ö ñ44 ° d ONLN d ¥ s • ~ ∫ )-long ° d ONLN d π s “ ~´ )-.number of segments received that contained all ° d ONLN d Ë Å “ å *duplicate data ° d ONLN d ˜ ì x û Ñ ( ∫ ñ48 ° d ONLN d ˙ ì • û ∫ )-long ° d ONLN d ˇ ì “ ûo )- number of segments retransmitted ° d ONLN d! ® ≥ W ( œ < Result codes ° d ONLN d. ® x ≥ ì )ZnoErr ° d ONLN d4 ® “ ≥ ¯ )Zno error , N Helvetica Narrow
(Ÿ <58
))Chapter 4 / Transmission Control Protocol à :ÃÛ ˇ
x ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - Ï +rI C parameter-block definitions , Times
° d ONLN d 8 Æ CÙ +ZEThe following C type definitions are used with parameter-block Device ° d ONLN d d F Æ Q *Manager calls to TCP: ,
° d ONLN dªãä +ø Continued on following page , p AppleIcon p ° d ONLN d◊~â
)x. (Ÿï C parameter-block definitions
)à59 à pÃ) ˇv ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x ,™ +ñH3typedef void (*TCPIOCompletionProc) (struct TCPiopb ° d ONLN d 4 . x : ¢ **iopb); ° d ONLN d < @ x L8 * typedef unsigned short tcp_port; ° d ONLN d ] R x ^ *typedef unsigned char byte; ° d ONLN d y d x p *enum { /* ValidityFlags */ ° d ONLN d ñ r ñ ~ + timeoutValue = 0x80, ° d ONLN d ¨ Ä ñ å *timeoutAction = 0x40, ° d ONLN d √ é ñ ö *typeOfService = 0x20, ° d ONLN d ⁄ ú ñ ® ¸ *precedence = 0x10 ° d ONLN d Ï ™ x ∂ Ñ ( “ ñ}; ° d ONLN d Ô º x » ¸ *enum { /* TOSFlags */ ° d ONLN d ñ ÷ ˆ + lowDelay = 0x01, ° d ONLN d ÿ ñ ‰ *throughPut = 0x02, ° d ONLN d- Ê ñ Ú *reliability = 0x04 ° d ONLN d@ Ù x Ñ ( ñ}; ° d ONLN dC x * typedef struct TCPCreatePB { ° d ONLN da ñ fi + Ptr rcvBuff; ° d ONLN do" ñ., *unsigned long rcvBuffLen; ° d ONLN dä0 ñ<, *TCPNotifyProc notifyProc; ° d ONLN d•> ñJ ˆ *Ptr userDataPtr; ° d ONLN d∂L xX Δ (t ñ
}TCPCreatePB; , Times
° d ONLN dƒi xt¥ * AThe following parameter block is used with the TCPPassiveOpen and ° d ONLN dw xÇ ˙ *TCPActiveOpen commands:
° d ONLN d à xî *typedef struct TCPOpenPB { ° d ONLN d:ñ ñ¢ + byte ulpTimeoutValue; ° d ONLN dQ§ ñ∞ *byte ulpTimeoutAction; ° d ONLN di≤ ñæ *byte validityFlags; ° d ONLN d~¿ ñÃ, *byte commandTimeoutValue; ° d ONLN dôŒ ñ⁄ *ip_addr remoteHost; ° d ONLN dÆ‹ ñË *tcp_port remotePort; ° d ONLN dƒÍ ñˆ *ip_addr localHost; ° d ONLN dÿ¯ ñ *tcp_port localPort; ° d ONLN dÌ ñ Í *byte tosFlags; ° d ONLN d˝ ñ ˆ *byte precedence; ° d ONLN d" ñ. ¸ *Boolean dontFrag; ° d ONLN d"0 ñ< ˆ *byte timeToLive; ° d ONLN d4> ñJ Í *byte security; ° d ONLN dDL ñX *byte optionCnt; ° d ONLN dUZ ñf ¸ *byte options[40]; ° d ONLN dhh ñt ˆ *Ptr userDataPtr; ° d ONLN dyv xÇ ∫ (û ñ }TCPOpenPB; , N Helvetica Narrow (Ÿ <60
. ° d ONLN d Æ ,J +ÃHtypedef struct TCPSendPB { ° d ONLN d . à :J + byte ulpTimeoutValue; ° d ONLN d 3 < à HP *byte ulpTimeoutAction; ° d ONLN d K J à V> *byte validityFlags; ° d ONLN d ` X à d2 *Boolean pushFlag; ° d ONLN d s f à r> *Boolean urgentFlag; ° d ONLN d à t Ã Ä * Ptr wdsPtr; ° d ONLN d ï Ç Ã éV *unsigned long sendFree; ° d ONLN d Æ ê à úh *unsigned short sendLength; ° d ONLN d û à ™, *Ptr userDataPtr; ° d ONLN d € ¨ Æ ∏ ( ‘ à }TCPSendPB; , Times
° d ONLN d Á … Æ ‘˜ * DThe following parameter block is used with the TCPRcv, TCPBfrReturn, ° d ONLN d, ◊ Æ ‚F *and TCPNoCopyRcv commands:
° d ONLN dG Ë Æ Ù\ * typedef struct TCPReceivePB { ° d ONLN df ˆ Ãb + byte commandTimeoutValue; ° d ONLN dÅ Ã * byte filler; ° d ONLN dè à 2 *Boolean markFlag; ° d ONLN d¢ Ã,> *Boolean urgentFlag; ° d ONLN d∑. Ã: * Ptr rcvBuff; ° d ONLN d≈< ÃHh *unsigned short rcvBuffLen; ° d ONLN d·J ÃV * Ptr rdsPtr; ° d ONLN dÓX Ãdb *unsigned short rdsLength; ° d ONLN d f ÃrÜ * unsigned short secondTimeStamp; ° d ONLN d*t ÃÄ, *Ptr userDataPtr; ° d ONLN d;Ç Æé (™ Ã}TCPReceivePB; ° d ONLN dJî ƆP *typedef struct TCPClosePB { ° d ONLN dg¢ ÃÆJ + byte ulpTimeoutValue; ° d ONLN d~∞ úP *byte ulpTimeoutAction; ° d ONLN dñæ à > *byte validityFlags; ° d ONLN d´Ã Ãÿ, *Ptr userDataPtr; ° d ONLN dº⁄ ÆÊ ˆ ( à }TCPClosePB; ° d ONLN d…Ï Æ¯V * typedef struct HistoBucket { ° d ONLN dÁ˙ ÃJ + unsigned short value; ° d ONLN d˛ ÃP *unsigned long counter; ° d ONLN d Æ" ∫ (> Ã}; ° d ONLN d( Æ4D *#define NumOfHistoBuckets ° d ONLN d2(b4h )¥7 , N Helvetica Narrow
° d ONLN d4>ãI +) Continued on following page , p AppleIcon p ° d ONLN dP=H
)x. (Ÿï C parameter-block definitions
)â61 à pÃ) ˇ ä ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x ,J +ñH#typedef struct TCPConnectionStats { ° d ONLN d % . ñ :8 + unsigned long dataPktsRcvd; ° d ONLN d B < ñ H8 *unsigned long dataPktsSent; ° d ONLN d _ J ñ VD * unsigned long dataPktsResent; ° d ONLN d ~ X ñ d& *unsigned long bytesRcvd; ° d ONLN d ò f ñ r8 *unsigned long bytesRcvdDup; ° d ONLN d µ t ñ Äb *"unsigned long bytesRcvdPastWindow; ° d ONLN d Ÿ Ç ñ é& *unsigned long bytesSent; ° d ONLN d Û ê ñ ú2 *unsigned long bytesResent; ° d ONLN d û ñ ™P * unsigned short numHistoBuckets; ° d ONLN d0 ¨ ñ ∏Œ *4struct HistoBucket sentSizeHisto[NumOfHistoBuckets]; ° d ONLN df ∫ ñ Δ *unsigned short lastRTT; ° d ONLN d » ñ ‘ *unsigned short tmrSRTT; ° d ONLN dò ÷ ñ ‚8 *unsigned short rttVariance; ° d ONLN dµ ‰ ñ *unsigned short tmrRTO; ° d ONLN dÕ Ú ñ ˛ *byte sendTries; ° d ONLN dfi ñ *byte sourchQuenchRcvd; ° d ONLN dı x (6 ñ}TCPConnectionStats; ° d ONLN d
x, * typedef struct TCPStatusPB { ° d ONLN d(. ñ: + byte ulpTimeoutValue; ° d ONLN d?< ñH *byte ulpTimeoutAction; ° d ONLN dWJ ñV fi * long unused; ° d ONLN deX ñd *ip_addr remoteHost; ° d ONLN dzf ñr *tcp_port remotePort; ° d ONLN dêt ñÄ *ip_addr localHost; ° d ONLN d§Ç ñé *tcp_port localPort; ° d ONLN dπê ñú Í *byte tosFlags; ° d ONLN d…û ñ™ ˆ *byte precedence; ° d ONLN d€¨ ñ∏ *byte connectionState; ° d ONLN dÚ∫ ñΔ2 *unsigned short sendWindow; ° d ONLN d» ñ‘, *unsigned short rcvWindow; ° d ONLN d)÷ ñ‚J * unsigned short amtUnackedData; ° d ONLN dI‰ ñD * unsigned short amtUnreadData; ° d ONLN dhÚ ñ˛ *Ptr securityLevelPtr; ° d ONLN d ñ 2 *unsigned long sendUnacked; ° d ONLN dõ ñ *unsigned long sendNext; ° d ONLN d¥ ñ(P * unsigned long congestionWindow; ° d ONLN d’* ñ6 *unsigned long rcvNext; ° d ONLN dÌ8 ñD *unsigned long srtt; ° d ONLN dF ñR *unsigned long lastRTT; ° d ONLN dT ñ`D * unsigned long sendMaxSegSize; ° d ONLN d9b ñnÄ *'struct TCPConnectionStats *connStatPtr; ° d ONLN dbp ñ| ˆ *Ptr userDataPtr; ° d ONLN ds~ xä Δ (¶ ñ
. ° d ONLN d Æ ,P +ÃHtypedef struct TCPAbortPB { ° d ONLN d . à :, + Ptr userDataPtr; ° d ONLN d . < Æ H ˆ ( d à }TCPAbortPB; ° d ONLN d ; N Æ ZD *typedef struct TCPParam { ° d ONLN d V \ à hP + unsigned long tcpRtoA; ° d ONLN d n j à v\ *unsigned long tcpRtoMin; ° d ONLN d à x à Ñ\ *unsigned long tcpRtoMax; ° d ONLN d ¢ Ü Ã ít * unsigned long tcpMaxSegSize; ° d ONLN d ¿ î à †b *unsigned long tcpMaxConn; ° d ONLN d € ¢ à Æn *unsigned long tcpMaxWindow; ° d ONLN d ˜ ∞ Æ º Í ( ÿ Ã
}TCPParam; ° d ONLN d ¬ Æ ŒD *typedef struct TCPStats { ° d ONLN d – à ‹Ä + unsigned long tcpConnAttempts; ° d ONLN d= fi à Ít * unsigned long tcpConnOpened; ° d ONLN d[ Ï Ã ¯Ä * unsigned long tcpConnAccepted; ° d ONLN d{ ˙ Ãt * unsigned long tcpConnClosed; ° d ONLN dô Ãz * unsigned long tcpConnAborted; ° d ONLN d∏ Ã"h *unsigned long tcpOctetsIn; ° d ONLN d‘$ Ã0n *unsigned long tcpOctetsOut; ° d ONLN dÒ2 Ã>z * unsigned long tcpOctetsInDup; ° d ONLN d@ ÃLÜ * unsigned long tcpOctetsRetrans; ° d ONLN d1N ÃZn *unsigned long tcpInputPkts; ° d ONLN dN\ Ãht * unsigned long tcpOutputPkts; ° d ONLN dlj Ãvb *unsigned long tcpDupPkts; ° d ONLN dáx ÃÑz * unsigned long tcpRetransPkts; ° d ONLN d•Ü Æí Í (Æ Ã
}TCPStats; ° d ONLN d∞ò Ƨn * typedef struct TCPGlobalInfoPB { ° d ONLN d“¶ Ã≤z + struct TCPParam *tcpParamPtr; ° d ONLN dÒ¥ ÿz * struct TCPStats *tcpStatsPtr; ° d ONLN d¬ ÃŒb *StreamPtr *tcpCDBTable[]; ° d ONLN d+– Ë, *Ptr userDataPtr; ° d ONLN d=fi ÃÍí *!unsigned short maxTCPConnections; ° d ONLN d_Ï Æ¯ ( Ã}TCPGlobalInfoPB; , N Helvetica Narrow
° d ONLN dqã
+› Continued on following page , p AppleIcon p ° d ONLN dç
)x. (Ÿï C parameter-block definitions
)à63 à pÃ) ˇ< ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x , +ñHtypedef struct TCPiopb { ° d ONLN d . ñ : ¥ + char ° d ONLN d .J :å )¥ fill12[12]; ° d ONLN d - < ñ H ( d ¥TCPIOCompletionProc ° d ONLN d A <J Hò )¥
ioCompletion; ° d ONLN d P J ñ V ∫ ( r ¥short ° d ONLN d W JJ VÄ )¥ ioResult; ° d ONLN d b X ñ d ¥ ( Ä ¥char ° d ONLN d h XJ då )¥ *ioNamePtr; ° d ONLN d u f ñ r ∫ ( é ¥short ° d ONLN d | fJ rÜ )¥
ioVRefNum; ° d ONLN d à t ñ Ä ¥ ( ú ¥short ° d ONLN d é tJ ÄÜ )¥
tcpStream; ° d ONLN d ø û ñ ™ ¿ ( Δ ¥union { ° d ONLN d » ¨ ñ ∏ *struct TCPCreatePB ° d ONLN d € ¨J ∏t )¥create; ° d ONLN d  ∫ ¥ Δ ( ‚ “struct TCPOpenPB ° d ONLN d ˆ ∫J Δh )ñopen; ° d ONLN d ˛ » ¥ ‘ ( “struct TCPSendPB ° d ONLN d »J ‘h )ñsend; ° d ONLN d ÷ ¥ ‚& ( ˛ “struct TCPReceivePB ° d ONLN d+ ÷J ‚z )ñreceive; ° d ONLN d6 ‰ ¥ ( “struct TCPClosePB ° d ONLN dH ‰J n )ñclose; ° d ONLN dQ Ú ¥ ˛ ( “struct TCPAbortPB ° d ONLN dc ÚJ ˛n )ñabort; ° d ONLN dl ¥ (( “struct TCPStatusPB ° d ONLN d J t )ñstatus; ° d ONLN dâ ¥8 (6 “struct TCPGlobalInfoPB ° d ONLN d†Jå )ñ globalInfo; ° d ONLN dÆ ¥( (D “
} csParam; ° d ONLN dπ* x6 Æ (R ñ }TCPiopb; , N Helvetica Narrow (Ÿ <64
° d ONLN d A Æ Tå )ZName-to-Address Resolution , Times
° d ONLN d ™ Æ µ˙ *cHTextual names are resolved to IP addresses using internal caches and the ° d ONLN d f ∏ Æ √ *Gdomain name server. The AddressXlation interface accomplishes this task ° d ONLN d Æ Δ Æ — *Mby searching an internal table originally derived from the static file Hosts, ° d ONLN d ¸ ‘ Æ fl˜ *Emaking queries to domain name servers, and finding information in the ° d ONLN dB ‚ Æ Ìç */internal cache of domain name server responses. ˇÄ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - ƒ +<I The AddressXlation.h header file , Times
° d ONLN d ! 8 x CŒ +ZFThe AddressXlation.h interface supports the domain name resolver (DNR) ° d ONLN d h F x Qà *Kfunction using the procedure calls listed in Table 5-1 and described in the ° d ONLN d ¥ T x _ Œ *following sections.
° d ONLN d » p x { ú * Table 5-1 ° d ONLN d — p ú { )$ AddressXlation.h routines
° d ONLN d ˛ ñ x ° ´ ( Ω ñ OpenResolver ° d ONLN d ñ “ °å )Z3Opens the resolver and allocates internal resources ° d ONLN d? • x ∞ § ( à ñ StrToAddr ° d ONLN dI • “ ∞ú )Z6Converts an ASCII text string to the corresponding IP ° d ONLN dÄ ± “ º * address ° d ONLN dà ¿ x À § ( Á ñ AddrToStr ° d ONLN dí ¿ “ Àë )Z4Converts an IP address into its text dotted decimal ° d ONLN d« à “ ◊ * notation (W.X.Y.Z) ° d ONLN d⁄ € x Ê ° ( ñ EnumCache ° d ONLN d‰ € “ ʧ )Z6Enumerates all the name-to-address mappings cached by ° d ONLN d Á “ Ú ˛ * the resolver ° d ONLN d( ˆ x ™ ( ñ
AddrToName ° d ONLN d3 ˆ “ß )Z9Converts an IP address to its corresponding textual name ° d ONLN dm “
* using the resolver ° d ONLN dÄ x å (8 ñHInfo ° d ONLN dÜ “ ò )Z5Returns details about the system whose name is being ° d ONLN dº “( Ó * queried ° d ONLN dƒ, x7 í (S ñMXInfo ° d ONLN dÀ, “7° )Z7Returns mail box information for the system whose name ° d ONLN d8 “C * is being queried ° d ONLN dG xR ¨ (n ñ
CloseResolver ° d ONLN d"G “Rñ )Z6Closes the resolver and deallocates internal resources z îzÛ (Ÿ <66
° d ONLN d 4 x @ +Z#define NUM_ALT_ADDRS 4 ° d ONLN d + F x R *typedef struct hostInfo { ° d ONLN d F T ñ ` fi + int rtnCode; ° d ONLN d T b ñ n ˆ *char cname[255]; ° d ONLN d f p ñ |b *"unsigned long addr[NUM_ALT_ADDRS]; ° d ONLN d â ~ x ä Ñ ( ¶ ñ}; ° d ONLN d å ê x úV *%typedef pascal void (*ResultProcPtr)( ° d ONLN d ≥ û ñ ™D + struct hostInfo *hostInfoPtr, ° d ONLN d “ ¨ ñ ∏ *char *userDataPtr); ° d ONLN d Ê æ x ( Ê ñextern OSErr StrToAddr( ° d ONLN d ˇ Ã ñ ÿ + char *hostName, ° d ONLN d ⁄ ñ ÊD * struct hostInfo *hostInfoPtr, ° d ONLN d/ Ë ñ Ù, *ResultProcPtr ResultProc, ° d ONLN dJ ˆ ñ *char *userDataPtr); , Times
° d ONLN d^ x ç (3 ñThe
° d ONLN db ç Ω )hostInfo
° d ONLN dj Ω» )0= record is passed into the address translation routine in the
° d ONLN d® x% Æ (A ñ StrToAddr
° d ONLN d± Æ% ‹ )6 call. The
° d ONLN dº ‹% ).rtnCode
° d ONLN d√%À )*. indicates whether the result fields are valid ° d ONLN dÚ( x3 ‚ (O ñfor this call; a value of
° d ONLN d ' ‚3 )jnoErr
° d ONLN d( 3ø ) , indicates that the call was successful. The
° d ONLN d>5 xA ñ (] ñcname
° d ONLN dC6 ñA ) is the official name of the
° d ONLN d`5AB )|hostName
° d ONLN dh6BA∞ )0 that was specified. The
° d ONLN dÅ5∞A» )naddr
° d ONLN dÜD xO (k ñ%array is a list of addresses for the
° d ONLN d´COB )öhostName
° d ONLN d≥DBO¬ )0 that was specified. Multiple ° d ONLN d—R x]l (y ñ5addresses are returned for hosts that are multihomed.
° d ONLN df xr Æ * StrToAddr
° d ONLN dg Ær— )6C takes a string in one of two forms and translates it into a 32-bit ° d ONLN dTu xÄ≈ (ú ñKIP address. The string can be in IP dot notation (that is, W.X.Y.Z) or in a ° d ONLN d†É xéÕ *Hvalid domain name syntax. The translated address is returned immediately ° d ONLN dÈë xú∂ *Iif the passed in host is in IP dot notation or if the matching address is ° d ONLN d3ü x™æ *Jcontained in the local cache. If the address is not contained in the local ° d ONLN d~≠ x∏ ® * cache, the
° d ONLN d⨠®∏ “ )0rtnCode
° d ONLN dê≠ “∏ fl )* is
° d ONLN dî¨ fl∏ )
cacheFault
° d ONLN dû≠∏™ )< and the domain name server is ° d ONLN dΩª xΔ‘ (‚ ñJcontacted to resolve the address. When the response has been returned from ° d ONLN d… x‘° *<the domain name server or the domain name query has not been ° d ONLN dE◊ x‚ ¯ * successfully completed, the
° d ONLN da÷ ¯‚4 )Ä
ResultProc
° d ONLN dk◊4‚ª )< is called with the appropriate
° d ONLN d㉠x ¢ ( ñrtnCode
° d ONLN dí ¢* )* and return information. The
° d ONLN d؉*` )à StrToAddr
° d ONLN d∏Â`— )6 procedure can be called ° d ONLN d—Û x˛ ñ ( ñwith a
° d ONLN dÿÚ ñ˛ ÿ ) userDataPtr
° d ONLN d„Û ÿ˛≤ )B/, which is user-defined and not modified by the ° d ONLN d x ∑ (( ñresolver. The
° d ONLN d! ∑ ˘ )? userDataPtr
° d ONLN d, ˘ \ )B is returned when the
° d ONLN dB \ ò )c
ResultProc
° d ONLN dLò √ )< is called. ° d ONLN dX xŒ (6 ñJDomain names that contain no domain name delimiters, that is, no dots (.), ° d ONLN d£ x(≤ *Dare terminated with the domain name suffix specified for the default ° d ONLN dË+ x6— *Jdomain name server in the Control Panel. They are terminated with a dot if ° d ONLN d39 xD ‡ *no default is specified.
° d ONLN d ' !v , )0 field had a syntax error ° d ONLN d A 3 Æ > fl ( Z Ã
cacheFault ° d ONLN d L 35 >˜ )á)the name specified cannot be found in the ° d ONLN d v A5 LO *cache ° d ONLN d | S Æ ^ Î ( z à noResultProc ° d ONLN d â S5 ^¸ )á,no result procedure is passed to the address ° d ONLN d ∂ a5 l
*/translation call when the resolver must be used ° d ONLN d Ê o5 zä *to find the address ° d ONLN d ˙ Å Æ å Ú ( ® à noNameServer ° d ONLN d Å5 å )á-no name server can be found for the specified ° d ONLN d5 è5 ök * name string ° d ONLN dA ° Æ ¨ Ï ( » à authNameErr ° d ONLN dM °5 ¨… )á this domain name does not exist ° d ONLN dm ≥ Æ æ € ( ⁄ ÃnoAnsErr ° d ONLN dv ≥5 æ€ )á"none of the known name servers are ° d ONLN dô ¡5 Ãi *
responding ° d ONLN d§ ” Æ fi Õ ( ˙ ÃdnrErr ° d ONLN d´ ”5 fi )á,the domain name server has returned an error ° d ONLN dÿ Â Æ Ò ( à outOfMemory ° d ONLN d‰ Â5 ˇ )á+not enough memory is available to issue the ° d ONLN d Û5 ˛ˇ *'needed domain name resolver (DNR) query ° d ONLN d85 Æ *or to build the DNR cache ° d ONLN dR Æ Â (: Ã
notOpenErr ° d ONLN d]5 ì )áthe driver isn’t open , N Helvetica Narrow
° d ONLN ds9 TG µ (c rThe AddrToStr call
° d ONLN dÜN ÆZ
+Z:extern OSErr AddrToStr(unsigned long addr, char *addrStr);
° d ONLN d¡d Æo *JThe AddrToStr call takes an IP address and returns a string with the ASCII ° d ONLN d r Æ} *Hequivalent of the form W.X.Y.Z where W, X, Y, and Z are decimal numbers. ° d ONLN dUÄ Æã˝ *JThe application must provide the storage for the return string. The string ° d ONLN d†é Æôj *&can have a maximum length of 16 bytes. ° d ONLN d«£ TÆ ç ( r Result codes ° d ONLN d‘£ ÆÆ Â )Z
notOpenErr ° d ONLN dfl£5Æì )áthe driver isn’t open (Ÿà The AddressXlation.h header file
)ï69 à pÃ) ˇ ö ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - á +<IThe EnumCache call ,
Courier
° d ONLN d 4 x @ +Ztypedef enum AddrClasses { ° d ONLN d / B ñ N ∫ + A = 1, ° d ONLN d 7 P ñ \ ® *NS, ° d ONLN d < ^ ñ j “ *
CNAME = 5, ° d ONLN d H l ñ x ÿ * HINFO = 13, ° d ONLN d U z ñ Ü Δ *MX = 15, ° d ONLN d _ à ñ î ¸ *lastClass = 32767 ° d ONLN d q ñ x ¢ Δ ( æ ñ
}AddrClasses; ° d ONLN d ® x ¥> *!typedef struct cacheEntryRecord { ° d ONLN d ¢ ∂ ñ ¬ fi + char *cname; ° d ONLN d ∞ ƒ ñ – *unsigned short type; ° d ONLN d Δ “ ñ fi2 *unsigned short cacheClass; ° d ONLN d ‚ ‡ ñ Ï *unsigned long ttl; ° d ONLN d ˆ Ó ñ ˙ ¿ *union { ° d ONLN d ¸ ¥ ˆ + char *name; ° d ONLN d
¥ *ip_addr *addr; ° d ONLN d ñ$ Δ (@ ¥} rdata; ° d ONLN d'& x2 Ñ (N ñ}; ° d ONLN d*8 xDn *)typedef pascal void (*EnumResultProcPtr)( ° d ONLN dUF ñR§ + -struct cacheEntryRecord *cacheEntryRecordPtr, ° d ONLN dÑT ñ` *char *userDataPtr); ° d ONLN dòf xr (é ñextern OSErr EnumCache( ° d ONLN d±t ñÄ\ + !EnumResultProcPtr enumResultProc, ° d ONLN d‘Ç ñé *char *userDataPtr); , Times
° d ONLN dËó x¢Ø (æ ñGIf the application wants to enumerate all the entries in the cache, the ° d ONLN d0• x∞à *FEnumCache procedure should be called. This procedure returns no errors ° d ONLN dw≥ xæÕ *Hand has completed enumerating the cache when it returns. For every entry ° d ONLN d¿¡ xà ¥ *in the cache,
° d ONLN dŒ¿ ¥Ã )<enumResultProc
° d ONLN d‹¡Ã¡ )T+ is called with a pointer to a cache entry. ° d ONLN dœ x⁄# (ˆ ñ&The fields and values returned in the
° d ONLN d.Œ#⁄É )´CacheEntryRecord
° d ONLN d>œÉ⁄« )` are as follows: ° d ONLN dO‰ xÔ ë ( ñname ° d ONLN dT‰ “Ô< )ZThe name of the entry. ° d ONLN dk˘ x å ( ñtype ° d ONLN dp˘ “T )Z The type of the entry, where ° d ONLN dç ‘ fl +— ° d ONLN dé fl Ê ) A ° d ONLN dè Êú )) (value = 1) is an address. The value of
° d ONLN d∏ú∫ )∂rdata
° d ONLN dΩ∫“ ) is an
° d ONLN dƒ ‡ ¯ (< ˛addr
° d ONLN d» ¯ ˚ ). ° d ONLN d # ‘. fl (J Ú— ° d ONLN dÀ# fl. Ï ) NS ° d ONLN dÕ# Ï.± )
, (value = 2) is a name server. The value of
° d ONLN d˘"±.œ )≈rdata
° d ONLN dˇ1 ‡< Ú (X ˛is a ° d ONLN d1 Ú< )name ° d ONLN d1< ) . ° d ONLN d
? ‘J fl (f Ú— ° d ONLN d ? flJ ) CNAME ° d ONLN d?J∫ )%* (value = 5) is an alias for the canonical ° d ONLN d;M ‡X (t ˛name (
. ° d ONLN d ! Æ , ∑ +ÃHttl ° d ONLN d ! , )Z9The time that the entry has to live in the cache relative ° d ONLN d > / :û *!to the current time (GetCurrent). ° d ONLN d ` D Æ O ≈ ( k Ãrdata ° d ONLN d f D O )ZThe ,
Courier
° d ONLN d j C O; )rdata
° d ONLN d o D; Oı ) ) field as determined by the type of entry ° d ONLN d ô R ]Ä ( y& specified in the type field. ° d ONLN d ∂ g T r ç ( é r Result codes ° d ONLN d √ g Æ r  )Z
notOpenErr ° d ONLN d Œ g rf )Zthe driver isn’t open , N Helvetica Narrow (Ÿà The AddressXlation.h header file
)ñ71 à pÃ) ˇ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - é +<IThe AddrToName call ,
Courier
° d ONLN d 4 x @ +Zextern OSErr AddrToName( ° d ONLN d . B ñ N ‰ +
ip_addr addr, ° d ONLN d = P ñ \D * struct hostInfo *hostInfoPtr, ° d ONLN d \ ^ ñ j, *ResultProcPtr ResultProc, ° d ONLN d w l ñ x *char *userDataPtr); , Times
° d ONLN då ¨6 ∑“ )0# record, the result procedure to be ° d ONLN d∞ ∫ x ≈î ( · ñ@notified with the result, and an optional user data pointer. The ° d ONLN dÒ » x ”™ *?AddrToName call always returns immediately with the return code
° d ONLN d1 ’ x · ¥ *
cacheFault
° d ONLN d; ÷ ¥ ·
)< or the return code
° d ONLN dO ’
·U )Y noNameServer
° d ONLN d[ ÷U ·… )H if no name server can be ° d ONLN du ‰ x Ô– ( ñKfound in the internal name server lists that can resolve the DNR query. The ° d ONLN d¡ Ú x ˝Ã *Mpassed-in result procedure is called with the appropriate result code. If the ° d ONLN d x ∑ *result code is
cacheFault ° d ONLN dõ# ˇ.¡ )á)the name specified cannot be found in the ° d ONLN d«1 ˇ< *cache ° d ONLN dÕC xN º (j ñ noNameServer ° d ONLN d⁄C ˇN” )á-no name server can be found for the specified ° d ONLN dQ ˇ\5 * name string ° d ONLN dc xn ∂ (ä ñ authNameErr ° d ONLN d c ˇnì )á this domain name does not exist ° d ONLN d@u xÄ • (ú ñnoAnsErr ° d ONLN dIu ˇÄ• )á"none of the known name servers are ° d ONLN dlÉ ˇé3 *
responding ° d ONLN dwï x† ó (º ñdnrErr ° d ONLN d~ï ˇ†— )á,the domain name server has returned an error ° d ONLN d´ß x≤ ª (Œ ñ outOfMemory ° d ONLN d∑ß ˇ≤… )á+not enough memory is available to issue the ° d ONLN d„µ ˇ¿‘ **needed DNR query or to build the DNR cache ° d ONLN d« x“ Ø (Ó ñ
notOpenErr ° d ONLN d« ˇ“] )áthe driver isn’t open
(Ÿ <72
)&Chapter 5 / Name-to-Address Resolution à :ÃÛ ˇ
é ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - ô +rIThe HInfo call ,
Courier
° d ONLN d 4 Æ @D +Ztypedef struct HinfoRec { ° d ONLN d * B à N2 + char cpuType[30]; ° d ONLN d = P à \, *char osType[30]; ° d ONLN d N ^ Æ j ∫ ( Ü Ã}; ° d ONLN d R p Æ |J *typedef struct returnRec { ° d ONLN d n ~ à ä + int rtnCode; ° d ONLN d | å à ò, *char cname[255]; ° d ONLN d é ö à ¶ ˆ *union { ° d ONLN d ò ® Í ¥∂ + "unsigned long addr[NUM_ALT_ADDRS]; ° d ONLN d Ω ∂ Í ¬n *struct HInfoRec hinfo; ° d ONLN d ÷ ƒ Í –J *struct MXRec mx; ° d ONLN d Ë “ à fi ¸ ( ˙ Í} rdata; ° d ONLN d Ò ‡ Æ Ï ∫ ( Ã}; ° d ONLN d Ù Ú Æ ˛í *&typedef pascal void (*ResultProc2Ptr)( ° d ONLN d Ã Ü + struct returnRec *returnRecPtr, ° d ONLN d> Ã> *char *userDataPtr); ° d ONLN dR Æ, (H Ãextern OSErr HInfo( ° d ONLN dg. Ã:& + char *hostName, ° d ONLN dx< ÃHÜ * struct returnRec *returnRecPtr, ° d ONLN dôJ ÃVh *ResultProc2Ptr resultProc, ° d ONLN dµX Ãd> *char *userDataPtr); , Times
° d ONLN d…n ÆyÁ (ï ÃCThe HInfo call returns details about the system whose name is being ° d ONLN d
| ÆáX *'queried. The call returns two strings,
° d ONLN d4{XáÇ )™cpuType
° d ONLN d;|Çáô )* and
° d ONLN d@{ôáΩ )osType
° d ONLN dF|Ωá )$, that specify in ° d ONLN dXä Æï∞ (± Ã6ASCII the values of the CPU and operating system type. ° d ONLN dèü Æ™ *KThe HInfo call follows the calling conventions for queries described in the ° d ONLN d€≠ Æ∏á *.section “DNR Operation” later in this chapter. ° d ONLN d
¬ TÕ ç (È r Result codes ° d ONLN d¬ ÆÕ ˆ )Z
nameSyntaxErr ° d ONLN d%¬5ÕF )áthe
° d ONLN d)¡FÕv )hostName
° d ONLN d1¬vÕ„ )0 field has a syntax error ° d ONLN dK‘ Æfl Ú (˚ à noNameServer ° d ONLN dX‘5fl )á-no name server can be found for the specified ° d ONLN dÜ‚5Ìk * name string ° d ONLN díÙ Æˇ € ( ÃnoAnsErr ° d ONLN dõÙ5ˇ€ )á"none of the known name servers are ° d ONLN dæ5
i *
responding ° d ONLN d… Æ Õ (; ÃdnrErr ° d ONLN d–5 )á,the domain name server has returned an error ° d ONLN d˝& Æ1 Ò (M Ã outOfMemory ° d ONLN d &51ˇ )á+not enough memory is available to issue the ° d ONLN d545?
**needed DNR query or to build the DNR cache ° d ONLN d`F ÆQ Â (m Ã
notOpenErr ° d ONLN dkF5Qì )áthe driver isn’t open +5l The AddressXlation.h header file
)ï73 à pÃ) ˇ t ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - o +<IThe MXInfo call ,
Courier
° d ONLN d 4 x @ ¸ +Ztypedef struct MXRec { ° d ONLN d ( B ñ N2 + unsigned short preference; ° d ONLN d D P ñ \ *char exchange[255]; ° d ONLN d Y ^ ñ j ¢ *}; ° d ONLN d \ p x | ( ò ñtypedef struct returnRec { ° d ONLN d x ~ ñ ä fi + int rtnCode; ° d ONLN d Ü å ñ ò ˆ *char cname[255]; ° d ONLN d ò ö ñ ¶ ¿ *union { ° d ONLN d ¢ ® ¥ ¥Ä + "unsigned long addr[NUM_ALT_ADDRS]; ° d ONLN d « ∂ ¥ ¬8 *struct HInfoRec hinfo; ° d ONLN d ‡ ƒ ¥ – *struct MXRec mx; ° d ONLN d Ú “ ñ fi Δ ( ˙ ¥} rdata; ° d ONLN d ˚ ‡ x Ï Ñ ( ñ}; ° d ONLN d ˛ Ú x ˛\ *&typedef pascal void (*ResultProc2Ptr)( ° d ONLN d& ñ P + struct returnRec *returnRecPtr, ° d ONLN dH ñ *char *userDataPtr); ° d ONLN d\ x, Í (H ñextern OSerr MXInfo ° d ONLN dq. ñ: ˆ + (char *hostName, ° d ONLN dÉ< ñHP * struct returnRec *returnRecPtr, ° d ONLN d§J ñV2 *ResultProc2Ptr resultProc, ° d ONLN d¿X ñd *char *userDataPtr); , Times
° d ONLN d‘n xyŒ (ï ñFThe MXInfo call returns mail box information for the system whose name ° d ONLN d| xáE *.is being queried. The call returns two values: , p AppleIcon p
° d ONLN dJê xò } *n
° d ONLN dLé Öô‘ )
Jpreference, an unsigned integer specifying the preference that is given to ° d ONLN dóú Öß ˚ *the returned system name p
° d ONLN d∞∞ x∏ } (’ ñn
° d ONLN d≤Æ ÖπŒ )
Gexchange, the domain name for the system that is receiving mail for the ° d ONLN d˙º Ö« ƒ *specified host ° d ONLN d — x‹« (¯ ñHThe MXInfo call follows the calling conventions for queries described in ° d ONLN dRfl xÍb *2the section “DNR Operation” later in this chapter. ° d ONLN dÖÙ ˇ W ( < Result codes ° d ONLN díÙ xˇ ¿ )Z
nameSyntaxErr ° d ONLN d†Ù ˇˇ )áthe
° d ONLN d§Ûˇ@ )hostName
° d ONLN d¨Ù@ˇ≠ )0 field has a syntax error ° d ONLN dΔ x º (- ñ noNameServer ° d ONLN d” ˇ” )á-no name server can be found for the specified ° d ONLN d ˇ 5 * name string ° d ONLN d
& x1 • (M ñnoAnsErr ° d ONLN d& ˇ1• )á"none of the known name servers are ° d ONLN d94 ˇ?3 *
responding ° d ONLN dDF xQ ó (m ñdnrErr ° d ONLN dKF ˇQ— )á,the domain name server has returned an error ° d ONLN dxX xc ª ( ñ outOfMemory ° d ONLN dÑX ˇc… )á+not enough memory is available to issue the ° d ONLN d∞f ˇq… *'needed domain name resolver (DNR) query ° d ONLN dÿt ˇx *or to build the DNR cache ° d ONLN dÛÜ xë Ø (≠ ñ
notOpenErr ° d ONLN d˛Ü ˇë] )áthe driver isn’t open
(Ÿ <74
)&Chapter 5 / Name-to-Address Resolution à :ÃÛ ˇ
º ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - « +rIThe CloseResolver call ,
Courier
° d ONLN d 4 Æ @b +Z extern OSerr CloseResolver (); , Times
° d ONLN d 6 J Æ U *LBefore the application exits, the CloseResolver call must be made to release ° d ONLN d É X Æ c *Imemory structures and terminate all outstanding domain name server calls. ° d ONLN d Õ f Æ q˙ *JCloseResolver must not be called until all outstanding resolver calls have ° d ONLN d t Æ ˙ *been completed. ° d ONLN d( â T î ç ( ∞ r Result codes ° d ONLN d5 â Æ î Â )Z
notOpenErr ° d ONLN d@ â5 îì )áthe driver isn’t open
° d ONLN dV Ø T Ω ( Ÿ r"Binding the DNR to the application
° d ONLN dy » Æ ” +ZEThe domain name resolver (DNR) in the MacTCP driver is implemented as ° d ONLN dø ÷ Æ ·q **a code resource in the MacTCP driver file. ° d ONLN dÍ Î Æ ˆÛ *FA file called DNR.c in the Libraries Folder of the MacTCP release disk ° d ONLN d1 ˘ Æ˙ *Cprovides a working example of how to open the DNR. Compile and link ° d ONLN du Æ *Kthis file to your application. MPW version 3.2 produces a file called DNR.o ° d ONLN d¡ Æ *Kin the Libraries Folder of the MacTCP release disk that provides procedural ° d ONLN d
# Æ. *Jaccess to the DNR. Sources have also been provided if you need to port the ° d ONLN dX1 Æ<~ *,functionality to another development system. ° d ONLN dÖF ÆQ *KTo use the DNR, the application must first find the procedure pointers that ° d ONLN d—T Æ_˙ *Gare part of the DNR resource. In Macintosh system software version 6.0. ° d ONLN dT˙_ˇ ({x ° d ONLN dTˇ_ ), ° d ONLN db Æm' (â Ãthe DNR resource, named ° d ONLN d3b'm@ )ydnrp, ° d ONLN d8b@m )0 is attached to the driver file, which is in the ° d ONLN dip Æ{˘ (ó ÃKSystem Folder of the startup disk. The driver file is of type cdev, creator ° d ONLN dµ~ ÆâÔ *Iztcp. In Macintosh system software version 7.0, the driver file is in the ° d ONLN dˇå Æó‹ *AControl Panels folder (see the chapter “The Finder Interface” in ° d ONLN d@å‹ó¯ (≥˙Inside ° d ONLN dGö Æ• fi (¡ à Macintosh ° d ONLN dPö fi•˝ )0;, Volume VI). The resource can be opened using the Resource ° d ONLN då® Æ≥J (œ à Manager routines in the Toolbox. ° d ONLN dÆΩ Æ» *MOnce the resource is opened, the first long word of the resource is a pointer ° d ONLN d¸À Æ÷ *Gto a procedure that jumps to the correct DNR procedure. You should make ° d ONLN dDŸ Ɖ‹ *Dcalls to this procedure using the procedure index value as the first ° d ONLN dâÁ ÆÚ *Iargument of the call, followed by the arguments for the procedure as they ° d ONLN d”ı Æ *Jare specified in the AddressXlation.h interface. The procedure assignments ° d ONLN d Æ Ô *are as follows: ° d ONLN d. Æ# Ó * OpenResolver ° d ONLN d;# )Z1 ° d ONLN d=- Æ8 Ó (T Ã
CloseResolver ° d ONLN dK-8 )Z2 ° d ONLN dMB ÆM ‡ (i à StrToAddr ° d ONLN dWBM )Z3 ° d ONLN dYW Æb ‡ (~ à AddrToStr ° d ONLN dcWb )Z4 ° d ONLN del Æw Ê (ì à EnumCache ° d ONLN dolw )Z5 ° d ONLN dqÅ Æå Ó (® Ã
AddrToName ° d ONLN d|Åå )Z6 +[1"Binding the DNR to the application
)ú75 Ã pÃ) ˇ
t ◊# ˇ ˇˇˇˇ # ◊
d , Times
. ° d ONLN d ! x , î +ñHHInfo ° d ONLN d ! “ , ÿ )Z7 ° d ONLN d 6 x A û ( ] ñMXInfo ° d ONLN d 6 “ A ÿ )Z8 , N Helvetica Narrow
° d ONLN d \ j k ( Ü <
DNR operation
° d ONLN d u x Ä— +ZIThis section describes how the domain name server (DNS) list is used when ° d ONLN d i É x é € *making DNS queries. ° d ONLN d } ò x £… *KIf a default name extension and server are identified in the Control Panel, ° d ONLN d … ¶ x ±∂ *Fthey are used for all nonqualified requests. For example, if the name ,
Courier
° d ONLN d •∂ ±‘ ( Õ‘homer
° d ONLN d ¥ x ø[ ( € ñ2is passed to the DNR and the default extension is
° d ONLN dG ≥[ øó )„
pundit.edu
° d ONLN dQ ¥ó øΔ )<
, the name
° d ONLN d\ ¡ x Õ ÿ ( È ñhomer.pundit.edu
° d ONLN dl ¬ ÿ Õö )`+ is used in the query; however, if the name
° d ONLN dò œ x € ¸ ( ˜ ñhomer.drama.pundit.edu
° d ONLN dÆ – ¸ €º )Ñ+ is passed to the DNR, the extension is not ° d ONLN d⁄ fi x È ® ( ñ appended. ° d ONLN d‰ Û x ˛∫ *AThe extension of the name passed to the DNR determines which name ° d ONLN d& x ø *Jservers are chosen. Servers that match the full extension are found first, ° d ONLN dq xÆ *Ffollowed by servers that serve the ancestor of the full extension (for ° d ONLN d∏ x( ‚ *example, for the name
° d ONLN dŒ ‚(f )jhomer.drama.pundit.edu
° d ONLN d‰ f(… )Ñ, the server that serves
° d ONLN d˝* x6 ÿ (R ñdrama.pundit.edu
° d ONLN d
+ ÿ6‘ )`8 would be found first followed by the server that serves
° d ONLN dF8 xD ¥ (` ñ
pundit.edu
° d ONLN dP9 ¥D“ )<B). If no servers are found, the default server is used. If you did ° d ONLN dìG xR (n ñ#not set a default, the DNR returns
° d ONLN d∂FR\ )ú noNameServer
° d ONLN d¬G\RŒ )H. In the MacTCP Control ° d ONLN d⁄U x`ø (| ñGPanel, you should enter a default domain and select the Default button. ° d ONLN d"j xu¡ *JOnce a list of servers that support the domain is found, those servers are ° d ONLN dmx xÉÀ *Lqueried in the order of their distance from the querying host. First servers ° d ONLN d∫Ü xëƒ *Hon the local network are queried, followed by servers on other networks. ° d ONLN dî xü√ *DWhen you use the AddrToName query, you must select a default server.
° d ONLN d A Æ Tq )ZMiscellaneous Interfaces , Times
° d ONLN d ™ Æ µˇ *cGThis chapter describes types that are found throughout the programmatic ° d ONLN d c ∏ Æ √w *+interfaces supplied with the MacTCP driver. à pÃ) ˇ
◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d - ö +<IMacTCPCommontypes , Times
° d ONLN d 8 x C√ +ZFThis file defines result code name-to-number mapping, Internet Control ° d ONLN d Y F x Qó *<Message Protocol (ICMP) message report structures, and other ° d ONLN d ñ T x _g *1miscellaneous types throughout the MacTCP driver.
° d ONLN d » o x | º * Result codes
° d ONLN d ’ á x í∞ *?The result codes in MacTCPCommontypes are described as follows. ° d ONLN d ï x †Ø *EChapters 3, 4, and 5 contain specific occurrences of the result codes ° d ONLN d[ £ x Æ È *described in this section. ,
Courier
° d ONLN dv ¥ x ¿ ‰ *#define inProgress
° d ONLN dâ µ, ¿2 )¥1 ° d ONLN dã µY ¿∫ )-When an IOPB is still ° d ONLN d° √Y ŒÑ * pending,
° d ONLN d™ ¬Ñ Œ¥ )+ioResult
° d ONLN d≤ √¥ ŒÕ )0 is set ° d ONLN d∫ —Y ‹e ( ¯wto
° d ONLN dΩ –e ‹° )
inProgress
° d ONLN d« —° ‹§ )<.
° d ONLN d… ‚ x Ó Í (
ñ#define ipBadLapErr
° d ONLN d› „, ÓN )¥-23000 ° d ONLN d‰ „Y Ó¡ )-Unable to initialize the ° d ONLN d˝ ÒY ¸¿ *local network handler.
° d ONLN d x (* ñ#define ipBadCnfgErr
° d ONLN d),N )¥-23001 ° d ONLN d0YÕ )-The manually set address ° d ONLN dIY – *is configured improperly.
° d ONLN dc" x. Í (J ñ#define ipNoCnfgErr
° d ONLN dw#,.N )¥-23002 ° d ONLN d~#Y.Õ )-A configuration resource ° d ONLN dó1Y<â * is missing.
° d ONLN d£B xN fi (j ñ#define ipLoadErr
° d ONLN dµC,NN )¥-23003 ° d ONLN dºCYN… )-Not enough room in the ° d ONLN d”QY\• *application heap ° d ONLN d‰_Yj™ *(Macintosh 512K ° d ONLN dÙmYx§ *enhanced only).
° d ONLN dñª,ΔN )¥-23005 ° d ONLN dùªYΔ¬ )-A TCPClose command ° d ONLN d∞…Y‘‘ *was already issued so there ° d ONLN dÃ◊Y‚” *is no more data to send on ° d ONLN dÁÂY¢ *this connection.
° d ONLN d¯ˆ x ˆ ( ñ#define invalidLength
° d ONLN d˜,N )¥-23006 ° d ONLN d˜YÀ )-The total amount of data ° d ONLN d.Y“ *described by the WDS was ° d ONLN dGY √ *either 0 or greater than ° d ONLN d`!Y,ó *
65,535 bytes.
° d ONLN dn2 x> (Z ñ#define connectionExists
° d ONLN dá3,>N )¥-23007 ° d ONLN dé3Y>… )-The TCP or UDP stream ° d ONLN d§AYLµ *already has an open ° d ONLN d∏OYZè * connection.
° d ONLN dƒ` xl& (à ñ #define connectionDoesntExist
. ° d ONLN d Æ ,\ +ÃH #define insufficientResources , Times
° d ONLN d !b ,Ñ )¥-23009 ° d ONLN d % !è ,˝ )-64 TCP or UDP streams ° d ONLN d ; /è :fl *are already open.
° d ONLN d M @ Æ L> ( h Ã#define invalidStreamPtr
° d ONLN d f Ab LÑ )¥-23010 ° d ONLN d m Aè L
)-The specified TCP or UDP ° d ONLN d Ü Oè ZÊ *stream is not open.
° d ONLN d ö ` Æ lD ( à Ã#define streamAlreadyOpen
° d ONLN d ¥ ab lÑ )¥-23011 ° d ONLN d ª aè l )-An open stream is already ° d ONLN d ’ oè z˛ *using this receive buffer ° d ONLN d Ô }è à• *area.
° d ONLN d ı é Æ öV ( ∂ Ã #define connectionTerminated
° d ONLN d èb öÑ )¥-23012 ° d ONLN d èè ö )-The TCP connection was ° d ONLN d0 ùè ® *broken; the reason will be ° d ONLN dK ´è ∂ *given in a terminate ASR.
° d ONLN de º Æ », ( ‰ Ã#define invalidBufPtr
° d ONLN d{ Ωb »Ñ )¥-23013 ° d ONLN dÇ Ωè »˙ )-The receive buffer area ° d ONLN dö Àè ÷Δ *
pointer is 0.
° d ONLN d® ‹ Æ Ë ( Ã#define invalidRDS
° d ONLN dª ›b ËÑ )¥-23014 ° d ONLN d¬ ›è Ë )-The RDS refers to receive ° d ONLN d‹ Îè ˆ *buffers not owned by the ° d ONLN dı ˘è• *user.
° d ONLN d˚
Æ (2 Ã#define invalidWDS
° d ONLN d bÑ )¥-23014 ° d ONLN d è˛ )-The WDS pointer was 0.
° d ONLN d, Æ( (D Ã#define openFailed
° d ONLN d? b(Ñ )¥-23015 ° d ONLN dF è(Ú )-The connection came ° d ONLN dZ+è6Ì *halfway up and then ° d ONLN dn9èD¨ *failed.
° d ONLN dvJ ÆV2 (r Ã#define commandTimeout
° d ONLN dçKbVÑ )¥-23016 ° d ONLN dîKèV˛ )-The specified command ° d ONLN d™Yèd *action was not completed ° d ONLN d√gèrÏ *in the specified time ° d ONLN dŸuèÄ∞ *period.
° d ONLN d·Ü Æí8 (Æ Ã#define duplicateSocket
° d ONLN d˘ábíÑ )¥-23017 ° d ONLN d áèí )-A stream is already open ° d ONLN dïè† *using this local UDP port ° d ONLN d3£èÆÓ *or a TCP connection ° d ONLN dG±èº *already exists between this ° d ONLN dcøè *local IP address and TCP ° d ONLN d|Õèÿı *port, and the specified ° d ONLN dî€èÊı *remote IP address and ° d ONLN d™ÈèÙº * TCP port.
° d ONLN d¥˙ Æ, (" Ã#define ipDontFragErr
° d ONLN d ˚bÑ )¥-23032 ° d ONLN d—˚è )-The packet is too large to ° d ONLN dÏ è *send without fragmenting ° d ONLN dè"ˇ *and the Don’t Fragment ° d ONLN d %è0Ω * flag is set.
° d ONLN d)6 ÆB, (^ Ã#define ipDestDeadErr
° d ONLN d?7bBÑ )¥-23033 ° d ONLN dF7èB )-The destination host is not ° d ONLN dbEèPÙ *responding to address ° d ONLN dxSè^Ë *resolution requests.
° d ONLN dçd ÆpJ (å Ã#define icmpEchoTimeoutErr
° d ONLN d®ebpÑ )¥-23035 ° d ONLN dØeèp )-The icmp echo packet was ° d ONLN d»sè~˙ *not responded to in the ° d ONLN d‡Åèå *indicated timeout period. , N Helvetica Narrow *1MacTCPCommontypes
)p79 Ã pÃ) ˇ
◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x , ¸ +ñH#define ipNoFragMemErr , Times
° d ONLN d !, ,N )¥-23036 ° d ONLN d !Y ,“ )- Insufficient internal driver ° d ONLN d ; /Y :± *buffers available to ° d ONLN d P =Y HΔ *fragment this packet on ° d ONLN d h KY Vq *send.
° d ONLN d n \ x h ‰ ( Ñ ñ#define ipRouteErr
° d ONLN d Å ], hN )¥-23037 ° d ONLN d à ]Y hΔ )-No gateway available to ° d ONLN d † kY v‘ *manage routing of packets ° d ONLN d ∫ yY Ñú *to off-network ° d ONLN d … áY íí *
destinations.
° d ONLN d ◊ ò x § ˆ ( ¿ ñ#define nameSyntaxErr
° d ONLN d Ì ô, §N )¥-23041 ° d ONLN d Ù ôY §n )-The
° d ONLN d ¯ òn §û )hostName
° d ONLN d ôû §“ )0 field had a ° d ONLN d
ßY ≤Œ ( Œwsyntax error. The address ° d ONLN d' µY ¿Ã *was given in dot notation ° d ONLN dA √Y Œœ *(that is, W.X.Y.Z) and did ° d ONLN d\ —Y ‹— *not conform to the syntax ° d ONLN dv flY Í™ *for an IP address.
° d ONLN dâ x ¸ ‰ ( ñ#define cacheFault
° d ONLN dú Ò, ¸N )¥-23042 ° d ONLN d£ ÒY ¸≥ )-The name specified ° d ONLN d∂ ˇY
¬ *cannot be found in the ° d ONLN dÕ
YÕ *cache. The domain name ° d ONLN d‰Y&ƒ *resolver will now query ° d ONLN d¸)Y4« *the domain name server ° d ONLN d7YB» *and return the answer in ° d ONLN d,EYP… *the call-back procedure.
° d ONLN dEV xb (~ ñ#define noResultProc
° d ONLN dZW,bN )¥-23043 ° d ONLN daWYbø )-No result procedure is ° d ONLN dxeYpπ *passed to the address ° d ONLN désY~» *translation call when the ° d ONLN d®ÅYå» *resolver must be used to ° d ONLN d¡èYö• *find the address.
° d ONLN d”† x¨ (» ñ#define noNameServer
° d ONLN dË°,¨N )¥-23044 ° d ONLN dÔ°Y¨¬ )-No name server can be ° d ONLN dØY∫√ *found for the specified ° d ONLN d ΩY»í * name string.
° d ONLN d*Œ x⁄ Í (ˆ ñ#define authNameErr
° d ONLN d>œ,⁄N )¥-23045 ° d ONLN dEœY⁄« )-This domain name does ° d ONLN d[›YËÉ *
not exist.
° d ONLN dfÓ x˙ ÿ ( ñ#define noAnsErr
° d ONLN dwÔ,˙N )¥-23046 ° d ONLN d~ÔY˙Œ )-None of the known name ° d ONLN dï˝Y√ *servers are responding.
° d ONLN d≠ x à (6 ñ#define dnrErr
° d ONLN dº,N )¥-23047 ° d ONLN d√YÀ )-The domain name server ° d ONLN d⁄ Y(Ω *has returned an error.
° d ONLN dÒ. x: Í (V ñ#define outOfMemory
° d ONLN d/,:N )¥-23048 ° d ONLN d /Y:ƒ )-Not enough memory is ° d ONLN d!=YH∑ *available to issue the ° d ONLN d8KYVÀ *needed DNR query or to ° d ONLN dOYYdº *build the DNR cache. , N Helvetica Narrow
(Ÿ <80
)$Chapter 6 / Miscellaneous Interfaces à :ÃÛ ˇ
◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d Æ , +ÃHMiscellaneous types , Times
° d ONLN d 7 Æ BÌ *DThis section describes types that are common to all the programmatic ° d ONLN d Y E Æ PC * interfaces in the MacTCP driver. ,
Courier
° d ONLN d z V Æ b8 *#define BYTES_16WORD 2 ° d ONLN d í VD b¯ )ñ /* bytes per 16 bit ip word */ ° d ONLN d ± d Æ p8 ( å Ã#define BYTES_32WORD 4 ° d ONLN d … dD p¯ )ñ /* bytes per 32 bit ip word */ ° d ONLN d Ë r Æ ~8 ( ö Ã#define BYTES_64WORD 8 ° d ONLN d rD ~¯ )ñ /* bytes per 64 bit ip word */ ° d ONLN d Ñ Æ êJ ( ¨ Ãtypedef unsigned char b_8; ° d ONLN d: Ñb ê⁄ )¥/* 8-bit quantity */ ° d ONLN dO í Æ ûV ( ∫ à typedef unsigned short b_16; ° d ONLN dl íb û‡ )¥/* 16-bit quantity */ ° d ONLN dÇ † Æ ¨P ( » Ãtypedef unsigned long b_32; ° d ONLN dû †b ¨‡ )¥/* 32-bit quantity */ ° d ONLN d¥ ≤ Æ æ, ( ⁄ Ãtypedef b_32 ip_addr; ° d ONLN dÀ ≤b æ )¥/* IP address is 32-bits */ ° d ONLN dÁ ¿ Æ Ã& ( Ë Ãtypedef b_16 ip_port ° d ONLN d¸ “ Æ fi\ * typedef struct ip_addrbytes { ° d ONLN d ‡ Ã Ï ˆ + union { ° d ONLN d% Ó Í ˙& +
b_32 addr; ° d ONLN d2 ¸ Í8 *
char byte[4]; ° d ONLN dB
Í *} a; ° d ONLN dH Ã$& (@ Í} ip_addrbytes; ° d ONLN dX* Æ6D (R Ãtypedef struct wdsEntry { ° d ONLN ds8 ÃDP + unsigned short length; ° d ONLN dä8bDÊ )ñ/* length of buffer */ ° d ONLN d¢F ÃR (n Í char * ptr; ° d ONLN d∞FbRÏ )ñ/* pointer to buffer */ ° d ONLN d…T Ã` (| Í } wdsEntry; ° d ONLN d’f ÆrD (é Ãtypedef struct rdsEntry { ° d ONLN dt ÃÄP + unsigned short length; ° d ONLN dtbÄÊ )ñ/* length of buffer */ ° d ONLN d Ç Ãé (™ Í char * ptr; ° d ONLN d-ÇbéÏ )ñ/* pointer to buffer */ ° d ONLN dFê Ãú (∏ Í } rdsEntry; ° d ONLN dR¢ ÆÆn ( à typedef unsigned long BufferPtr; ° d ONLN ds¥ Æ¿n * typedef unsigned long StreamPtr;
° d ONLN dî– Æ›∏ * 3Internet Control Message Protocol report structures
° d ONLN d»Ë ÆÛ˚ *FIn TCP and UDP, the ASR routine can be called with an Internet Control ° d ONLN dˆ Ư *EMessage Protocol (ICMP) message. This section describes the types and ° d ONLN dU ÆF * structures of the ICMP messages.
° d ONLN dv Æ!J *typedef enum ICMPMsgType { ° d ONLN dí# Ã/¬ + )netUnreach, hostUnreach, protocolUnreach, ° d ONLN dΩ1 Ã=¬ *)portUnreach, fragReqd, sourceRouteFailed, ° d ONLN dÈ? ÃK¬ *)timeExceeded, parmProblem, missingOption, ° d ONLN dM ÃYV *lastICMPMsgType = 65535 ° d ONLN d.[ Ãg *} ICMPMsgType;
+√VMacTCPCommontypes
)q81 à pÃ) ˇ D ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x , +ñHtypedef struct ICMPReport { ° d ONLN d . ñ : + StreamPtr streamPtr; ° d ONLN d 3 < ñ H *ip_addr localHost; ° d ONLN d G J ñ V *ip_port localPort; ° d ONLN d [ X ñ d *ip_addr remoteHost; ° d ONLN d p f ñ r *ip_port remotePort; ° d ONLN d Ö t ñ Ä ¸ *short reportType; ° d ONLN d ò Ç ñ éV * unsigned short optionalAddlInfo; ° d ONLN d ∫ ê ñ úb *"unsigned long optionalAddlInfoPtr; ° d ONLN d fi û ñ ™ ‰ *
} ICMPReport; , Times
° d ONLN d Ï ¥ x ø≠ ( € ñ?Refer to the section “UDP Asynchronous Notification Routine” in ° d ONLN d, ¬ x Õ‘ *FChapter 3 and “TCP Asynchronous Notification Routine” in Chapter 4 for ° d ONLN ds – x €X *1details on how the ICMP report structure is used. , N Helvetica Narrow
° d ONLN d• ˆ g ( < GetMyIPAddr
° d ONLN d± xª +ZGThis section describes how an application obtains the IP address of the ° d ONLN d˘ x(æ *Cmachine on which it is running. GetMyIPAddr describes the parameter ° d ONLN d=+ x6Ã *Jblock that makes the PBControl call that returns the IP address and subnet ° d ONLN dà9 xDÆ *Fmask of the local host. The csCode for this call is 15, and the driver ° d ONLN dœG xR{ *7reference number is returned from the Open Driver call.
° d ONLN dX xd *#define ipctlGetAddr ° d ONLN d Xd )ñ15 ° d ONLN d X,d∂ ) /* csCode to get our IP ° d ONLN d>f,rh *
address */ ° d ONLN dIx xÑ († ñ#define IPParamBlockHeader ° d ONLN ddx,Ñ2 )¥\ ° d ONLN dgÜ ñí (Æ ¥struct QElem *qLink; ° d ONLN d|Ü,í2 )ñ\ ° d ONLN dî ñ† fi (º ¥ short qType; ° d ONLN déî,†2 )ñ\ ° d ONLN dë¢ ñÆ ‰ ( ¥
short ioTrap; ° d ONLN d°¢,Æ2 )ñ\ ° d ONLN d§∞ ñº Í (ÿ ¥Ptr ioCmdAddr; ° d ONLN dµ∞,º2 )ñ\ ° d ONLN d∏æ ñ (Ê ¥ProcPtr ioCompletion; ° d ONLN dŒæ, 2 )ñ\ ° d ONLN d—à ñÿ (Ù ¥OSErr ioResult; ° d ONLN d‚Ã,ÿ2 )ñ\ ° d ONLN dÂ⁄ ñÊ ( ¥StringPtr ioNamePtr; ° d ONLN d˙⁄,Ê2 )ñ\ ° d ONLN d˝Ë ñÙ ˆ ( ¥short ioVRefNum; ° d ONLN dË,Ù2 )ñ\ ° d ONLN dˆ ñ ˆ ( ¥short ioCRefNum; ° d ONLN d$ˆ,2 )ñ\ ° d ONLN d' ñ fi (, ¥ short csCode ° d ONLN d4 x" ˆ (> ñstruct IPParamBlock { ° d ONLN dK$ ñ0 + IPParamBlockHeader; ° d ONLN d`$,0¬ )ñ/* standard I/O header */ ° d ONLN d{2 ñ> (Z ¥ip_addr ourAddress; ° d ONLN dê2,>§ )ñ/* our IP address */ ° d ONLN d¶@ ñL ˆ (h ¥long ourNetMask; ° d ONLN d∏@,L™ )ñ/* our IP net mask */ ° d ONLN dœN ñZ ¢ (v ¥};
° d ONLN d”d xo (ã ñ"The IP address is returned in the
° d ONLN dıcoL )ò
ourAddress
° d ONLN dˇdLoœ )< field and the subnet mask is ° d ONLN d r x} ø (ô ñreturned in the
° d ONLN d-q ø} ˚ )G
ourNetMask
° d ONLN d7r ˚} )< field.
(Ÿ <82
)$Chapter 6 / Miscellaneous Interfaces à :ÃÛ ˇ
X ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d T - é +rI ICMP echo , Times
° d ONLN d
8 Æ CÌ +ZBThe ICMP echo request message allows a host to determine whether a ° d ONLN d M F Æ Q
*Jremote host is operational without bringing up a protocol like TCP or UDP. ° d ONLN d ò T Æ _ *HICMP echo can also be used to determine the responsiveness of a network. ° d ONLN d · b Æ mñ *1The following interface to ICMP echo is provided: ,
Courier
° d ONLN d s Æ , *#define ipctlEchoICMP ° d ONLN d) sD P )ñ17 ° d ONLN d, Ö Æ ëP ( ≠ Ã#define ipmplEchoTimeoutErr ° d ONLN dH Öb ëÜ )¥-23035 ° d ONLN dO ó Æ £z ( ø Ã"typedef void (*ICMPEchoNotifyProc) ° d ONLN ds • à ±Ä + (struct ICMPParamBlock *iopb);
° d ONLN dí ª Æ Δ ( ‚ ÃKThe following structure is used to make the PBControl call initiate an ICMP ° d ONLN dfi … Æ ‘Ñ *0echo request. The destination address is in the
° d ONLN d »Ñ ‘ú )÷dest
° d ONLN d …ú ‘˝ ) field, and the data to ° d ONLN d* ◊ Æ ‚( ( ˛ Ãbe echoed is described by
° d ONLN dD ÷( ‚X )zwdsEntry
° d ONLN dL ◊X ‚Á )0! in the data field. The specified ° d ONLN dn Â Æ ( ÃItimeout indicates how long to wait for the echo reply. The icmpCompletion ° d ONLN d∏ Û Æ ˛ı *Iroutine is called either at timeout or when a packet is returned from the ° d ONLN d Æ ¥ *:remote site. When a timeout occurs, the result code in the
° d ONLN d= Æ *ICMPParamBlock
° d ONLN dK¸ )T1 is icmpEchoTimeoutErr. When an ICMP echo returns ° d ONLN d} Æ(¸ (D ÃKsuccessfully, the time in ticks when the reply was received is contained in ° d ONLN d…+ Æ6 ø *the
° d ONLN dÕ* ø6 ) echoReplyIn
° d ONLN dÿ+6 )B9 field. The time in ticks when the request was dispatched ° d ONLN d9 ÆD (` Ãis contained in the
° d ONLN d&8DY )WechoRequestOut
° d ONLN d49YD˝ )T$ field. The echoed data contains the ° d ONLN dYG ÆRV (n Ã%data received in the response packet. ° d ONLN d\ Æg‰ *DYou can send options in an echo packet by filling the options field. ° d ONLN dƒj Æu
*GOptions must be well-formed (see RFC 791) and terminated on a long word ° d ONLN d x ÆÉÌ *Gboundary. The length field specifies the length of the options field in ° d ONLN dTÜ Æë˜ *Ibytes. The icmpCompletion routine is called with the options field set if ° d ONLN dûî Æü *Joptions are found in the echo response packet. The userdata pointer can be ° d ONLN dÈ¢ Æ≠º *;passed into the echo call and is returned unmodified in the ° d ONLN d%∞ ƪ" *icmpCompletion routine.
° d ONLN d=¡ ÆÕ, *struct IPParamBlock { ° d ONLN dTœ À> + IPParamBlockHeader; ° d ONLN di› ÃÈ ¸ *struct { ° d ONLN dtΠ͘8 +
ip_addr dest; ° d ONLN dÑ˘ Í> *wdsEntry data; ° d ONLN dï Í> *short timeout; ° d ONLN d¶ Í!2 * Ptr options; ° d ONLN dµ# Í/Ä *unsigned short optLength; ° d ONLN d—1 Í=∂ *"ICMPEchoNotifyProc icmpCompletion; ° d ONLN dˆ? ÍKÜ *unsigned long userDataPtr; ° d ONLN dM ÍY, * } IPEchoPB; ° d ONLN d [ Ãg ÿ (É Í};
+ˆV ICMP echo
)=83 à pÃ) ˇ∂ ◊# ˇ ˇˇˇˇ # ◊
d ,
Courier
. ° d ONLN d x , +ñHstruct ICMPParamBlock { ° d ONLN d . ñ : + IPParamBlockHeader; ° d ONLN d . < ñ H *short params [11]; ° d ONLN d B J ñ V Δ *struct { ° d ONLN d M X ¥ d\ + unsigned long echoRequstOut; ° d ONLN d l f ¥ rP *unsigned long echoReplyIn; ° d ONLN d â t ¥ ÄV *struct rdsEntry echoedData; ° d ONLN d ß Ç ¥ é ¸ * Ptr options; ° d ONLN d ∂ ê ¥ úP *unsigned long userDataPtr; ° d ONLN d ” û ¥ ™ *} icmpEchoInfo; ° d ONLN d ‰ ¨ ñ ∏ ¢ ( ‘ ¥}; , N Helvetica Narrow (Ÿ <84
. ° d ONLN d A T T ù +rnAppendix ° d ONLN d A Æ T ˝ )Z Constants , Times
° d ONLN d ™ Æ µ˛ *cCThis appendix presents command codes, UDP asynchronous event codes, ° d ONLN d W ∏ Æ √€ *>TCP asynchronous event codes, and reasons for TCP termination.
° d ONLN d ñ ” Æ ‡ *
Command codes
° d ONLN d § Î Æ ˆ · * UDPCreate ° d ONLN d Æ Îb ˆn )¥20 ° d ONLN d ± ˘ Æ € ( ÃUDPRead ° d ONLN d π ˘bn )¥21 ° d ONLN d º Æ Ú (. à UDPBfrReturn ° d ONLN d …bn )¥22 ° d ONLN d Ã Æ ‹ (< ÃUDPWrite ° d ONLN d ’b n )¥23 ° d ONLN d ÿ# Æ. Ê (J Ã
UDPRelease ° d ONLN d „#b.n )¥24 ° d ONLN d Ê1 Æ< (X Ã
UDPMaxMTUSize ° d ONLN d Ù1b<n )¥25 ° d ONLN d ˜? ÆJ fl (f à UDPStatus ° d ONLN d?bJn )¥26 ° d ONLN dM ÆX ˙ (t ÃUDPMultiCreate ° d ONLN dMbXn )¥27 ° d ONLN d[ Æf Ù (Ç Ã UDPMultiSend ° d ONLN d#[bfn )¥28 ° d ONLN d&i Æt Ù (ê à UDPMultiRead ° d ONLN d3ibtn )¥29 ° d ONLN d6w ÆÇ fl (û à TCPCreate ° d ONLN d@wbÇn )¥30 ° d ONLN dCÖ Æê ˚ (¨ ÃTCPPassiveOpen ° d ONLN dRÖbên )¥31 ° d ONLN dUì Æû ¯ (∫ Ã
TCPActiveOpen ° d ONLN dcìbûn )¥32 ° d ONLN df° ƨ Ÿ (» ÃTCPSend ° d ONLN dn°b¨n )¥34 ° d ONLN dqØ Æ∫ ˙ (÷ à TCPNoCopyRcv ° d ONLN d~Øb∫n )¥35 ° d ONLN dÅΩ Æ» (‰ à TCPBfrReturn ° d ONLN déΩb»n )¥36 ° d ONLN dëÀ Æ÷ ” (Ú ÃTCPRcv ° d ONLN dòÀb÷n )¥37 ° d ONLN dõŸ Ɖ € ( ÃTCPClose ° d ONLN d§Ÿb‰n )¥38 ° d ONLN dßÁ ÆÚ › ( ÃTCPAbort ° d ONLN d∞ÁbÚn )¥39 ° d ONLN d≥ı Æ › ( à TCPStatus ° d ONLN dΩıb n )¥40 ° d ONLN d¿ Æ ‰ (* Ã
TCPRelease ° d ONLN dÀbn )¥42 ° d ONLN dŒ Æ ı (8 Ã
TCPGlobalInfo ° d ONLN d‹b n )¥43
° d ONLN dfl, Æ9V (U Ã UDP asynchronous event codes
° d ONLN d¸D ÆO · * data arrival ° d ONLN d DbOh )¥1 ° d ONLN d R Æ] (y ÃICMP message received ° d ONLN d!Rb]h )¥2 à pÃ) ˇ‰ ◊# ˇ ˇˇˇˇ # ◊
d , N Helvetica Narrow
. ° d ONLN d x , +ñH TCP asynchronous event codes , Times
° d ONLN d 7 x B ô *closing ° d ONLN d % 7, B2 )¥1 ° d ONLN d ' E x P ≥ ( l ñ ULP timeout ° d ONLN d 3 E, P2 )¥2 ° d ONLN d 5 S x ^ £ ( z ñ terminate ° d ONLN d ? S, ^2 )¥3 ° d ONLN d A a x l ´ ( à ñ data arrival ° d ONLN d N a, l2 )¥4 ° d ONLN d P o x z  ( ñ ñurgent data outstanding ° d ONLN d h o, z2 )¥5 ° d ONLN d j } x à  ( § ñICMP message received ° d ONLN d Ä }, à2 )¥6
° d ONLN d Ç ò x •
( ¡ ñReasons for TCP termination
° d ONLN d û ∞ x ª ≥ * remote abort ° d ONLN d ´ ∞, ª2 )¥2 ° d ONLN d ≠ æ x … æ (  ñnetwork failure ° d ONLN d Ω æ, …2 )¥3 ° d ONLN d ø à x ◊ ( Û ñ security/precedence mismatch ° d ONLN d ‹ Ã, ◊2 )¥4 ° d ONLN d fi ⁄ x  ≥ ( ñ ULP timeout ° d ONLN d Í ⁄, Â2 )¥5 ° d ONLN d Ï Ë x Û ® ( ñ ULP abort ° d ONLN d ˆ Ë, Û2 )¥6 ° d ONLN d ¯ ˆ x ß ( ñ ULP close ° d ONLN d ˆ,2 )¥7 ° d ONLN d x ∏ (+ ñservice failure ° d ONLN d,2 )¥8
