For Beginners & Professional Hackers

home *** CD-ROM | disk | FTP | other *** search

/ For Beginners & Professional Hackers / cd.iso / docum / novell.doc / misc_nw.arj / IPX.TXT next >

Wrap

Text File | 1991-07-24 | 51.8 KB | 1,365 lines

File is created by Izotov Maxim 2:5020/10.4 with Documentation about IPX Advanced NetWare v2.0 Internetwork Packed Exchange Protocol ( IPX ) with Asynchronous Event Sheduler (AES) Specifications as of March 19,1986 Copyright (c) 1986 by Novell, Inc. All Rights Reserved NOTICE: The specifications contained in this document are intended to be complete and accurate. However, Novell reserved the right to change, augment, or diminish any or all of these specifications without notice. The scope of this document................................... 1 IPX overview................................................. 1 AES overview................................................. 1 IPX Internetwork packets......................................2 General Structure of IPX Packets .....................2 Structure of IPX Packet Headers ......................2 Description of Header Contents .......................3 Checksum .....................................3 Length .......................................3 Transport control ............................3 Packet type ..................................3 Destination Network ..........................4 Destination Node .............................4 Destination Socket ...........................4 Source Network ...............................5 Source Node ..................................5 Source Socket ................................6 Events and Event control blocks ......................7 General Structure ............................8 Description of Field Contents ................8 Link .................................8 ERS Address ..........................8 In use ...............................9 Completion Code ......................9 Socket Number .......................10 IPX Workspace .......................10 Driver Workspace ....................10 Immediate Address ...................10 Fragment Count ......................11 Fragment Description List ...........11 Event control blocks for special - purpose events ...12 General Structure ...........................12 Description of Field contents ...............12 Link.................................12 ERS address .........................12 In Use ..............................12 AES Workspace .......................12 - 1 - The scope of this document This document describes the IPX and AES programming interfaces as they have been implemented for 8088/8086-based workstations using MS/PC-DOS 2.x or 3.x and the corrasponding Advanced Netware v2.0 Workstations Shells. IPX Overview The Advanced Netware Internetwork Packet Exchange (IPX) Protocol is an implementations of Xerox's Internetwork PacketProtocol. The purpose of IPX is to allow applicatios running on a Netware workstation to take advantage of the Netware network drives to communicate with other workstations, servers, or devices on the internetwork. IPX is a service that provides to applications theability to send and receive individual packets on the internetwork. Internetwork packets are structured as defined by Xerox Network Standard (XNS). In the Advanced NetWare internetwork environment ( a network comprised of one or more LANs using Advanced NetWare), each node (a device attached to the network) has a unique internetwork address. Using IPX, a NetWare workstations may send or receive packets to or from any node on the internetwork. The routing of packets between nodes which reside on physically different LANs is largely automatic and transparent. This transparency is accomplished by the IPX facility in conjunction wich the services of Advanced NetWare bridges. The network drives make a "best effort" to physically deliver the packets but do not quarantee delivery. The implementation of reliable delivery, sequenced protocols, data stream, and other higher - level interconnection protocol may be buil upon the IPX packet protocol as needed by specific applications. The IPX protocol is intended to be used as a foundation upon which a variety of sophisticaated applicatons may be built, including communicaton servers, PC-to-mainframe concentrators, or direct interworkstations message systems. IPX is fully supported on all LAN topologies which are supported by Advanced NetWare v2.0. The IPX protocol provides full transparency and consistency across any Advanced NetWare internetworks. AES Overview The Asynchronous Event Sheduler (AES) is an auxilary service which provides a means of measuring elapsed time and/or triggering events at the conclusion of measured time intervals. Events are: the completion of an IPX send request, the reception of a packet in fulfillment of an IPPX listen request, or the expiration of an applicaton-defined time intervals. A service routine may be provided for each event; it will be called when the event occurs. If necessary, an event service routine may reshedule itself for delayed execution after a given time interval has elapsed. - 2 - IPX internetwork Packets The packet structure of IPX packets is precisely the structure of Xerox's XNS packets. The packet structure will be brifly outlined below; interessed users are referred to the Xerox document "Internetwork Transport Protocol" (Xerox Corporation, Xerox System Integration Standard; Stamford; Connecticut; December 1981; XSIS-028112) for a more detailed discussion of the XNS packet protocol. General Structure of IPX Packets An IPX packet consist of 30 bytes of header followd by 0 to 546 bytes of data. Thus, the minimum packet length is 30 bytes, and the maximum length is 576 bytes. Contents and structure of the data portion of packet are entirely the responsibility of the application(s) using IPX and may take format required. Structure of IPX Packet Headers The IPX header (first 30 bytes of all packets) must conform to the following format: Offset Field Size Data Type --------------------------------------------------------------- 0 Checksum 2 bytes h-l i's comlement integer 2 Length 2 bytes high-low unsigned integer 4 Transport Control 1 byte unsigned integer 5 Packet Type 1 byte unsigned integer 6 Destination Network 4 bytes high-low unsigned integer 10 Destination Node 6 bytes high-low unsigned integer 16 Destination Socket 2 bytes high-low unsigned integer 18 Source Network 4 bytes high-low unsigned integer 22 Source Node 6 bytes high-low unsigned integer 28 Source Socket 2 bytes high-low unsigned integer --------------------------------------------------------------- Note that numeric fields composed of more than 1 byte can be in two opposite formats: high-low(h-l) and low-high. High-low numbers contain the most significant byte in the first byte of the field, the next-most significant byte in the second byte, and so on, with the least significant byte appearing last. Low-high numbers are stored in exactly the opposite order. - 3 - Description of Header Contents Following is a basic descriptions of the meaning and use of each field in an IPX packed header. Checksum This field is a one's complement add and left cycle checksum of the 16-bit words in the packed header. This fiels will contain a -zero (FFFFh) if no checksum is desired. If a calculated checksum comes to -zero then it should be reset to +zero (0000h). Note that field is a checksumof the 30-byte header only. If applications wish to checksumtheir own data then they should provide their own checksumin some agreed-upon portion of data area. A given NetWareshell implementation may not verify this checksum when receiving a packed. If header checksum verification is required, then it should be performad by the application to whom the packed is delivered. Lenght This field contain the length of the complete network packed, which is the length of the header plus the length of the data section. Therefore, the minimum length of a packed is 30-bytes, and the maximum length of a packet is 576 bytes. Transport Control This field is used by Advanced Netware Internetwork Bridges and always set to zero before a packed is sent. Packed Type This field indicates the "type" of service offered or required by the packet; Xerox has defined the following values: 0 Unknown packed type 1 Routing Information Packet 2 Echo packet 3 Error packet 4 Packet Exchange Packet 5 Sequenced Packet Protocol Packet 16-31 Experimental Protocol Users are strongly encouraged to use either packet type 0 or packet type 4 in all their packets. - 4 - Destination Network This field contain a network number of the destination network where the node can be found to whom the packet is addressed. Under Advanced NetWare, networks connected on an internetwork are assigned 4-byte networks number by a network administrator. Each network on a connected internetwork is required to have a unique number. If this field is set to 0, the destination node is assumed to reside on the same physical network to which the source node is connected; the packet will be sent without involving an Advanced NetWare Internetwork Bridge. Destination Node This field contain a 6-byte number which identifis the physical address (on the destination network) of the node to which the packet is destined. Note that not all physical LAN topologies use same size address fields. A node on an EtherNet network would require all 6 bytes to specify its address, while a node on an OmniNet network would require only 1 byte. If a physical network needs less than 6 bytes to specify node addresses, then the portion of the address needed should occupy the least significant (last) portion of this field and the first bytes of the field should be set to zeroes. Setting all six bytes to FFh indicates that the packet should be broadcast to all nodes on the specified network. Broadcast to all nodes on a network may or may not be supported, depending on the physical characteristics (i.e. broadcast support) of the underlying physical network to which the packet is destined. Destination Socket This fiels contains the socket address of the software routine to which the packet is destined. Socket numbers are used to route packets to different software ruotines within a given node. Xerox has reserved certain sockets for special use. Pre-defined sockets are as follows: 1 Routing Information packet 2 Echo protocol packet 3 Error handler packet 32-63 Experimental - 5 - Sockets with numbers below 3.000 (decimal) are considered "well-known" sockets with statically assigned meanings, while sockets with numbers above 3.000 are dynamically assignable sockets. Applications developers that wish to produce a unique well-known socket may request that Xerox assign them one. A small fee and some amount of processing time may be required by Xerox. Novell has obtained from Xerox a set of sockets for various uses in the Advanced NetWare environment. For example, NetWare File Servers accept requests addressed to socket 0451h. Because it is unlickely that NetWare systems will frequently find themselves co-existing with bona fide Xerox networking software, Novell has decided to offer an alternative scheme for addressing socket numbers. Novell will administrate a list of sockets that will be well-known in all NetWare environments. Software developers writing value-added packetges for NetWare should find it simpler to obtain socket assigments from Novell. Numbers assigned by Novell begin at 8000h (32.768 decimal). Dynamic socket numbers begin at 4000h. Source Network This field contains the network number of the LAN to which the node that originated the packet is connected. This field may contain a value of zero, indicating an "unknown" number for the network to which the source node is physically connected. Incidentally, all packets with a zero in this field which pass through an Advanced NetWare Internetwork Bridge will have this field set with the real source network number. Thus, when a packet is received from a node on a different network, the Source Network field will always be set properly; packets originated by a node on the same network as the receiving node are the only packets which may still contain a value of zero in this field. Source Node This field contain the physicall address of the node from which the packet originated. How many bytes of this address are actually used to address the given node is a function of the physicall network to which the node is connected. See the related discussion in the preceding definition of the Destination Node field. - 6 - Source socket This field contain the socket address being used by the software routine that originated the packet. Although it is not required by the IPX protocol, it is usual for all stations communicating about a particular task in a peer-to-peer fashion to send and receive using the same socket number. In a client/server situation, the node which is acting as a server (perhaps a communicating gateway) would lickely be listening on a specific socket for frequest to service. In such cases, the source socket is not necessary the same or even significant; all that matters is that the server reply to the given source socket. For example, all Advanced NetWare file servers have the same socket address, but request to them may be originated by clients using any socket number. If software developers wish to have a uniquely assigned static socket to communicate on then they should contact Xerox or Novell to have a socket number assigned to him. (See the discussion of socket number allocation in the previous description of the Destination Socket field.) - 7 - Events and Event control blocks An Event Control Block (ECB) is a data structure that contains information required to coordinate the sheduling and/or activation of certain desired operations. Nearly all IPX or AES function act upon ECBs and/or the information they represent. There are two different kinds of events that may occur, events related to an IPX send or receive operation, and special-purpose events sheduled by an application. All events have an associated Event Control Block. For example, when an application desired to transmit an IPX packet, it must first prepare an ECB which describes where to obtain the packet data. The completed sending of a packet constitutes an "IPX send event". Linkwise, when an application desires to receive packets, it must make one or more ECBs available to IPX to describe where to store incoming packet data. The reception of a packet will cause an "IPX receive event". Additionally, an application may define and shedule a special-purpose event. An Event Control Block must be supplied to the AES along with a time interval. The AES will count-down the remaining time in the given interval. When the count-down timer reaches zero, the scheduled event occurs. There are two metods by which an event may be detected and acted upon by the application: polling an "in use" status flag or providing a service routine which can be invoked in an interrupt-like fashion. Every Event Control Block has an "in-use" status flag. This flag is automatically set to a non-zero value whenever an ECB is passed to an IPX or AES function to request an event. While this flag is non-zero, the application must not alter the contents of the Event Control Block. When IPX or the AES has finished performing the request function involving the specified ECB, the "in-use" flag will automatically be set to zero. At this point, the application has total freedom to manipulate the ECB and any of its associated data. An application may find, in some cases, that it is sufficient to periodically pool the status of all outstanding ECBs to determine when the awaited events have occured. Alternatively, every Event Control Block provides a way to specify the address of an Event Source Routine (ESR) which will be called in an interrupt-like fashion when the expected event has occured, use of an ESR more readily allows for real-time, asynchronous background operations to occur while the main body of the application performs some other activity. Event Control Blocks for IPX events have a different structure than ECBs intended for special events; honewer, congruent structuring of the first few fields in each type of ECB allow either kind of ECB to be used with the AES. Thus, an Event Service Routine invoked by an IPX event may use its associated ECB to re-shedule itself to "occur" at a later time. - 8 - Event Control Blocks for IPX events IPX function require a long form of Event Control Block ( an "IPX-ECB"). The format of an IPX-ECB and the meaning of each field will be described in this section. General Structure Offset Field Size Data Type ------ ----- ----- ---------- 0 Link 4 bytes 8086 long address (offset,segment) 4 ESR Address 4 bytes 8086 long address (offset,segment) 8 In Use 1 byte Unsigned integer 9 Completion Code 1 byte Unsigned integer 10 Socket Number 2 bytes High-low uinteger 12 IPX Workspace 4 bytes N/A 16 Driver Workspace 12 bytes N/A 28 Immediate Address 6 bytes High-low uns. integer 34 Fragment Count 2 bytes Low-high uns. integer 36 Fragment Descriptor-1 6 bytes Structure: Address 4 bytes 8086 long address (off,seg) Size 2 bytes Low-high uns.integer 30+n*6 Fragment Descriptor-n 6 bytes Structure As can be seen in the above structure, an IPX Event Control Block consist of two parts. The first, fixed portion (36 bytes long) contains status/information fields as well as a workspace for use by IPX and the network hardware drivers. The second, variable portion is a list of one or more buffer fragment addresses and lengths. This Fragment Descriptor List defines the places in memory from which a packet will be gathered for sending of to which a packet will be scattered upon reception. Description of Field Contents Link This field is maintained by IPX when the ECB is in use. When the ECB is not in use, the application may use this field, if desired. Most commonly, it would be used as a link field for keeping the ECB in free/ready lists or queues. ESR Address This field contains the address of an application - defined Event Service Routine (ESR) that IPX will call when the expected event (a packet send or receive operation) has been completed. - 9 - Because IPX maintains the In Use and Completion Code fields, it is possible for a programm to simply poll the status of its outstanding IPX request at appropriable intervals and not use a service routine at all. If no Event Service Routine is desired, then the ESR Address should be set to null (four bytes of zero). For a complete discussion of Event Service Ruotine usage, implementation and restriction quidelines, see the section entitled Event Service Routine Implementation. In Use This field contains a non-zero value whenever the ECB is in use by the IPX or AES. Following is a list of possible values and their meanings: FFh The ECB is in use for transmitting FEh The ECB is "listening" on a certain socket for incoming packets FDh The ECB has been schedulled with the AES and is awaiting the expiration of its time interval. FBh A send or receive event has occured, but yhe ECB is in a temporary holding queue, waiting to be officially processed IPX will reset this field to zero when the request action has been completed. Completion Code This field is set by the IPX routines to indicate the final status of the request represented by the Event Control Block. This field can not be considered valid until after IPX has reset the In Use field to zero. When an ECB has been given to IPx for the purpose of sending a packet, any of the following completion codes may be reported: 00h The send was completed successfully. This does not guarantee that the packet was received successfully. The packet may have been lost somewhere along the way, or even if it made it all the way to the target node there may have been no available receive buffers. FFh Physically unable to send the packet (Hardware or network failure.) FEh Packet Undeliverable (destination detected not to exist, no Internetwork Bridge available, or possible hardware failure). FDh Malformed packet (total length is less than 30 bytes of too large, first fragment is too small for IPX header, or Fragment Count is zero) FCh The send request was cancelled. - 10 - When an ECB has been given to IPX for the purpose of listening for incoming packets, any of the following completion codes may be reported: 00h The packet was received successfully FFh Socket Closed. The socket that ECB was supported to listen on was not open. FDh Packet overflow. A packet waas received, but the Fragment Count in the ECB was zero, or the available space described by the Fragment Descriptor was not large enough to contain the entire packet. FCh The liste request for this packet was canceled. Socket Number This field contains the number of the socket with which this ECB is associated. When an ECB is used for sending, this field contains the socket that the packet was sent from; when receiving, this field contains the socket that the packet was received on. IPX Workspace This four-byte fild is reserved for use by the IPX Routines. It does not need to be initialized to any values, and it must not be changed while the control block is being used by the IPX routines. When the ECB is not in use by the IPX, this area may be used in any fashion desired. Driver Workspace This twelve-byte field is reserved for use by the physical network drivers. It does not need to be initialized to any values, and it must not be changed while the control block is being used by the IPX routines. When the ECB is not in use by the IPX, this ares\a may be used in any fashions desired. Immediate Address This six-byte field contains the address of the node to which the packet was just sent or from which it just arrived. (this will be the address of an Internetwork Bridge on the local network if the packet was not to/from a node on the local network.) - 11 - This field contains a count of the number of buffer fragments from which packet shiuld be built for sending, or the number of buffers into which a received packet should be split. The value in this field must be greater than zero. A value of 1 (one) merely indicates that the packet is to be sent/received from/to a contuguous portion of memory. In other words, the first fragment contains the entire packet. Fragment Descriptor List A Fragment Descriptor precisely identifies where to find a piece of a packet to be sent, or where to place a piece of received packet. A fragment Descriptor has two component fields: Address An address of a bufferfrom which packet data should be gathered for a packet send or which packet data should be copied upon a packet receive. Size The size of the buffer fragment pointed to by the preceding Address. Any IPX Event Control Block must have at least one Fragment Descriptor, and an arbitraly number of additional descriptors, as necesssary. These descriptors constitute the Fragment Descriptor List. Allowing packet headers and data to be "gathered" from several places or "scattered" to several locations, the IPX functions remove the need for applications to repeatedly copy data to and from multiple locations. Note that sending and receiving complete packets from or into contiguous memory may be accomplished by setting the Fragment Count field to 1 (one) and providing only a single Fragment Descripror. Important When sending a packet, IPX will "gather" the packet contents from an arbitrary number of fragments; honewer, the buffer fragment identified by the first entry in the Fragment Descriptor List must be at least 30 bytes long and must contain the complete IPX packet header. The total packet size (thw sum of all the individual fragment sizes) must not exceed 576 bytes. - 12 - Event control blocks for special-purpose Events Special-purpose events sheduled by an applicaton are included to occur after the expiration of specified time interval. These events are represented by a short from Event Control Block (an "AES-ECB") and are sheduled directly through the Asynchronous Event Sheduler. General Structure Offset Field Size Data type ------ -------- ------ ---------------- 0 Link 4 bytes 8086 long address (offset,segment) 4 ESR Address 4 bytes 8086 long address 8 In Use 1 byte Unsigned integer 9 AES Workspace 5 bytes N/A Description of Field Contents Link This field is used by the AES when the ECB is in use. When the ECB is not in use, the application may use this field, if desired. Most commonly, it would be used as a link field for keeping the ECB in a free list or queue. ERS Address This field contains the address of an application-defined Event Service Routine (ESR) that the AES will call when the specified time interval has expired. Because the AES maintains the IN Use field, it is possible for a programm to simply pool the status of a sheduled event at appropriate intervals and not use a service routine at all. If no Event Service Routine is desired, then ESR Address should be set to null (four bytes of zero). In Use This field contains a value of ECB while the Event Control Block is being used by the AES to shedule a special event. The AES will reset this field to zero when the given time interval has expired. AES Workspace This field is reserved for use by the AES routines. It does not need to be initialized to any values, but it must not be changed while control block is in use. - 13 - Invoking IPX and AES function The remainder of this document will detail the IPX and AES programming interface that has been implemented for 8086/8088-based personal computers using MS/PC-DOS 2.x or 3.x and the Advanced NetWare Workstation Shell v2.0 or greater. this section will describe general implementation features of IPX and AES function; how to request their services, and how to monotor the status of those requests. Access Method The IPX and AES function are accessed through the Advanced Netware shell by loading register Bx with the appropriate function number and issuing a software interrupt 7Ah with registers and other informations prepared as documented for each function. Register Preservation IPX and AES functions preserve only register DS,SS,SP and processor flags. Interrupt States & Re-entrancy All IPX functions execute entirely in the interrupt-disabled state except for the Send Packet, Get Local Target, and Relinguish Control functions. If you are calling either of these functions from inside code that is running with interrupts disabled, you must be sure your code can survive if interrupts are enabled temporary by IPX. All IPX functions are re-entrant, and may even be called from Event Service Routines, with two exceptions: function Close Socket and Disconnect From Target can not be called from an ESR. All AES function execute with interrupts disabled and are therefore inherently re-entrant and cause no re-entrancy concerns at the application level. They may be called at any time, from any code. Use of Differency-sized ECBs IPX functions will operate only with IPX style (long) Event Control Blocks. AES functions will operate with IPX style (long) Event Control Blocks or AES style (short, special-purpose) Event Control Blocks. Monitoring the Status of a Request Whenever an Event Control Block is supplied for use in a send, listen, sheduling request (IPX-ECB), or special-purpose sheduling request (AES-ECB), the ECB's In Use field will be set to FFh, FEh, FDh, or FCh respectively. At other times the ECB's request cycle, there are two other temporary states that may be indicated by the ECB's In Use field. When the Driver concludes a send or receive, the associated ECB is placed in a holding queue, pending final release and the calling of its ESR, if any. During this time, the In Use field will contain a value of FBh. When the Driver is transferring packet data to or from the fragment buffers described by the ECB, the In Use field will contain a value of FAh. While an ECB's In Use field contains a non-zero value, no modifications can be made to either the ECB or any its associated buffers. Naturally, the ECB may not be used concurrently for another IPX or AES request. An ECB that is in use will remain so until the expected event occurs or the outstanding request is canceled. Note, however, that ECB may shuttle from the care of IPX directly to the care of the AES if the ECB's ESR decides to re-shedule itself. The value in the In Use field will reflect this change. (During the translation of ownership, the In Use field will contain a zero, but this will never be seen by the monitoring applicatondue to the interrupt-service nature of the ESR). An application may check the value of the In Use field at any time to determine when the request is no longer outstanding. An ECB is no longer in use when after the ECB's In Use field has been reset to zero. An other information in an Event Control Block can not be assumed valid until after the ECB's In Use field has been reset to zero. Numeric Field Format Conventions With regard to byte-ordering of numeric fields, the following rules apply: 1) Socket numbers are always in high-low order. Thus, when contained in an 8086 register, xL will contain the high byte and xH will contain the low byte. 2) Numeric fields in the IPX packet header are always in high-low order. 3) Values passed/returned in registers or numeric fields in ECBs are always in low-high order, with the exception of socket numbers, as noted in Rule I above. Prerequisite Conditions The documentation for each IPX or AES function will detail a set of conditions that are assumed to exit when the functions is invoked. These conditions include the setting of parameters in certain registers or the initialization of various ECB or IPX header fields. - 15 - Only the conditions that are expicitly mentioned in the function documentation's Assumes section need to be met by the programmer before invoking the function. Field Value Preservation For any particular IPX or AES function, the values of all the fields that are required to be initialised by the application will not be altered during the execution of the function, with one exception: when an IPX send broadcast request is canceled, the ESR Address field of the associated ECB will not be valid. Thus, an application may initialize certain ECBs buffer areas containing IPX headers once, are re-use those ECBs and buffers, changing only the data portion of the packets as needed. System Clock Ticks System clock ticks, as referred to this document, refer to the system clock ticks of an IBM PC. Those clock ticks occur approximataly 18.21 times a second. On other machines, clock ticks may only be available some other number of times per second. For example, suppose actual clock ticks were available only twice a second. In such a case, IPX will still handle all timing functions in terms of IBM PC clock tick values. A 36 tick delay will still indicate a delay of approximately two seconds. However, that timing will only be accurate to within plus or minus half a second. - 16 - IPX and AES function definition Open Socket Assumes ------- Bx has 0h Al has Socket Longevity Flag 00h = Stay open until closed of program terminates FFh = Stay open until closed Dx has Requested Socket Number 0000h = Let IPX dynamically assign a socket number non-zero= Open on this socket Returns ------- Al has Function Completion Code 00h = socket was successfully opened FFh = socket is already open. FEh = socket table is full. (IPX capacity is at maximum) Dx has Assign Socket Number Description This function opens a particular socket for use by the application. This function must be called before being able to send packets from or receive packets on a particular socket. If desired, IPX will dynamically assign you a socket number that is not already open on the workstation. The Requested Socket Number contained in DX is assumed to be in high-low order, that is, DL contains the HIGH half of the socket number, and DH contains the LOW half of the socket number that is to be opened. If this function is called with a Request Socket Number of zero, a socket number will be dynamically assigned by IPX. If the open request is successful, DX will contain the Assigned Socket Number when the function returns. This is the socket that was actually opened, as determined by the Requested Socket Number value. The Socket Longevity Flag indicates whether or not the socket is intended to remain open after the application terminates. A value of FFh will cause the socket to remain open until it is exclicitly closed. This feature is useful for terminate-and-stay resident applicatons that intaract with IPX. - 17 - As a precautionary measure when programming transient applications, programmers should always set the Socket Longevity Flag to zero, so that an unexpected termination of their code (by a control-break or control-C, for example) will cause the socket to be closed automatically when the application terminates and forces an end-of-job condition. All applications (except terminate-and-stay-resident applications) should close all of their open sockets before terminating. NOTE: If there are already as many open sockets open as IPX has internal table space to keep track of, the Function Completion Code returned in Al will be FEh. At the time of this specification's, IPX will support up to 50 open soockets on any workstation. - 18 - Close Socket Assumes Bx has 1h Dx has Number of socket to be closed Returns Nothing Description This function closes the specified socket. This functions cancels any IPX-ECBs associated with the indicated socket which are in use by IPX or AES for sending, listening, or sheduling purposes. Whenever an outstanding IPX request is canceled (by this function or by the Cancel Event function), the In Use field of any affected ECB is reset to zero and the Completion Code field is set to FCh, indicating that the request was canceled. NOTE: The Event Service Routine of a cancelled ECB is not called. Note that packets which arrive for a socket which is closed or has no outstanding listen requests will simply be ignored. Attempting to close a socket that was not open has no effect. WARNING Transient: applications must close all of their open sockets before terminating. Thus, only terminate-and-stay-resident applications should ever leave sockets open, and those sockets should be opened as "long-lived" sockets (see the description of Open Socket). If sockets are not closed before programm termination, a small but finite window exests where a packet may arruve and the service routine be called even though the program has issued an EXIT command to DOS. In such a case, corrupted pointers could conceivably cause the workstaton to "hang" with interrupts disabled. WARNING This function can not be called from an Event Service Routine, regardless of whether the ESR was called as the result of an IPX and AES event. - 19 - Get local Target Assumes Bx has 2h ES:SI has a pointer to a twelve-byte buffer ES:DI has a pointer to a six-byte buffer Returns Al has Function complete code 00h if a local target node was indentified FAh if there is no known path to the desired destination node Cx has one-way transport time to target node (only if al is 00h) Description This function determines the value which should be placed in an ECB's immediate Address fiels prior to passing the ECB to function Send Packet. Registers ES:SI point to a twelve-byte buffer which contains the full internetwork address of a node to which the application would like to send a packet. If there has been no prior communication with the destination node, then this function should be called once to determine what value should be placed in the Immediate Address field of each ECB that will be used in sending packets to the destination. The immediate address value will be placed in the six-byte buffer pointed to by ES:DI. If the ultimate destination node resides on the same local network, then local target address will be same as the node address portion of the full twelve-byte target address. If, however, the destination node resides on another network of the internetwork, the local target address returned will be the address of an Advanced NetWare Internetwork Bridge which will route the packet toward its final destination. Furthermore, once communicaton has been established with another node it is recommended that the Immediate Address field of send ECBs be set to the value contained the Immediate Address field of the ECB which was most recently used to receive a packet from the other node. Therefore, application which never initiate communication with other nodes but merely respond to incoming request will never need to call this function they may simply send reply packets to the same immediate address from which the request packets arrived. (Whenever a packet is received, the Immediate Address field of the receive ECB will be set by IPX to indicate the address from which the packet came.) - 20 - The Function Complete Code returned in Al will be FAh if this function could not find a path to the desired destination network. Note that the successful completion (Al returns with a 00h) of this function does not guarantee that the destination node exists; it only indicates the local address to which packet should be sent to start them on their journey. If this function was successful, a time calue will be returned in register Cx. This value indicates the amount of time (in system clock ticks) for a 576-byte packet to be sent to the target node. This time is a best-case time; a packet may take longer if network traffic is heavy. However, short packets may take less time because they have fewer bytes to be transmitted. Whun sending broadcasts, this function should still be called to determine the value to place in the send ECB's Immediate Address field. - 21 - Send Packet Assumes Bx has 3h ES:DI has a pointer to an Event Control Block In the ECB, the ESR Address,Socket Number, Immediate Address, Fragment Count, and Fragment Descriptor List fields are initialised. The first buffer fragment described by the Fragment Descriptor List is a least 30 bytes long and contains the packet's IPX header. In the IPX packet header, the Packet Type, Destination Network, Destination Node, and Destinaton Socket fields are initialised. Returns Nothing Description This function prepares the ECB and the IPX header of the associated packet and passes the ECB to network communication drivers to initialise the send operation. Having done so, this function returns immediality to the calling applicaton. This function will complete the packet's IPX header by filling in the Checksum, Length, Transport Control, Source Network, Source Node, and Source Socket fields. The latter calue is taken from the Socket Number field of the supplied ECB. IPX is designed to allow applications to function in fully asynchronous fashion with respect to the sending of internetwork packets; therefore, the send event can not be assumed concluded when this function returns. Using the information provided in the ECB, the network drivers will attempt to transmit the packet as soon as the network hardware is available and any other pending send requests have been serviced. The packet will be sent to the node on the immediately connected network that is indicated by the ECB's Immediate Address field. To understand how to determine the proper value for the Immediate Address field, see the documentation of function Get Local Target. While the packet is waiting to be transmitted, the In Use field in its ECB will contain a value of FFh. - 22 - When the drivers have finished their attempt to tramsmot the packet, the In Use field will be reset to zero. At this point, the Completion Code field in the ECB will contain the final status of the send request and the Event Service Routine pointed to by the ESR Address field will be called. If no ESR is desired, then the ESR Address field should be set to null (zeroes). If the request is cancelled by a Cancel Event or Close Socket function, the In Use field will be reset to zero and the Completion Code will be set to FCh. The ECB's Event Service Routine will not be called. Valid Completion Code values are: 00h The send was completed successfully. FFh Physical unable to send the packet (Hardware or network failure). FEh Packet Undeliverable. FDh Malformed packet (less that 30 or greater that 576 bytes, or list fragment too small for header, or Fragment Count was zero). FCh The send request was canceled by a Close Socket or Cancel Send/Listen function call. Some additional words of exlanation are necessary. The 00h completion code indicates that the packet was successfully transmitted does not guarantee that it was successfully received by the destination node. There conditions may exist to prevent successful reception of a packet: 1) The packet may be lost or garbled by the transmission media at any stage of its jouney; 2) The given destination node does not exist (some media protocols are unable to detect this condition when transmitting to a node that is aliegedly on the same physical network, and they can never detect this case if the packet must pass though an Internetwork Bridge); 3) There are no outstanding socket listen request in the destination node when the packet is received. The Packet Undeliverable code, FEh, can be generated in tree ways: 1) The packet was destined for a far network and no Advanced NetWare Internetwork Bridge with a path to the destination network could be found; - 23 - 2) The packet is destined for a node on the local network and the local network hardware detects that the target address is nonexistent or inactive (this is hardware-dependent); some drivers may have no way to distinguish between a hardware failure and a non-existent destination node and may indicate this error instead of an FFh; 3) The packet was destined for another socket on same machine that the packet was sent from, and that socket is not open or has pending listen request. IPX allow packets to be sent between a source and destination that reside in the same physical node ("Intranode routing"); even the source and destination sockets may be the same. This ability appers both to explicitly addressed packets as well as broadcast packets. Thus, an application that uses the same socket address for sending and receiving would always receive broadcasts it had sent to nodes on the same network as it was physically connected to. When an intranode packet is "sent", all related processing (including ESR execution) is performad in the same fashion as a normal transmission. Only then, if there is a listening ECB, will the packet be "received" and appropriately processed. The order of thus processing is guaranteed. - 24 - Listen for Packet Assumes Bx has 4h ES:DI has a pointer to an Event Control Block In the ECB, the ESR Address, Socket Number, Fragment Count, and Fragment Descriptor List fields are initialised. Returns Nothing Description This function delivers an ECB and the buffer space it describes to IPX the purpose of receiving an internetwork packet. Having done so, it returns immediately to calling the application. IPX is designed to allow applications to function in a fully asynchronous fashion with respect to the receiving of internetwork packets; therefore, this function only dedicates the given Event Control Block for use in receiving packets; the function does not wait for an actual packet to be received. The ECBwill only be used to receive packets that are destined to the socket given in the ECB's Socket Number field. The socket must be open before any listen requests may be made for that socket. (Incidentally, if a socket is not open, any incoming packets destined for that socket will be ignored.) When an ECB is donated to IPX for the purpose of listening for internetwork packets, the In Use field is set by IPX to FEh. This field will remain set until a receive event occurs, the request is canceled, or IPX judges the ECB to be unusable. After IPx has reset the In Use field to zero, one of the following values will be recorded in the Completion Code field of the ECB: 00h Packet was received successfully. FFh The socket upon which the ECB was to listen was not opened. FDh Packet overflow. A packet was received, but the ECB's Fragment Count was zero, or the available space defined by the 's Fragment Descriptor List was not large enough to contain the entire packet. FCh The send request was canceled by a Close Socket or Cancel Send/Listen function call. - 25 - If the request was cancelled by a Cancel Event or Close Socket function, the In Use field will be reset to zero and the Completion Code will be set to FCh, as listed above. The ECB's Event Service Routine will not be called. Otherwise, the Event Service Routine pointed to by the ECB's ESR Address field will be called. If no ESR is desired, then the ESR Address field should be set to null (zeroes). If the Completion Code field contains a value of 00h or FDh, then the Immediate Address field of the ECB will contain the address of node on the local natwork from which the packet was received. IPX imposes no limit on the number of ECBs that may be used concurrently for listening on a given socket. Many applications may enormosly by having several ECBs listening on the same socket. Note, however, that there is no guarantee that listening ECBs will be utilized by IPX in the same order they were offered. When a packet is received, IPX checks to see if there are any available ECBs listening on the appropriate socket. If there are no available ECBs, then the packet will simply be discarded. If there is only one ECB available, it will be used to disburse the packet data. If multiple Event Control Blocks are availablr, then IPX will coose one of them for use in disbusring the packet data. Listening ECBs are not chosen for use in receiving a packet on the basis of what order they were originally made available. When a packet arrives and an available ECB is chosen by IPX, the address of the node on the local network from which the packet came will be recorded in the Immediate Address field of the ECB. An application that desires to make a reply to the packet can copy this calue to the Immediate Address field of the ECB which will be used to send the reply. Replies made in this fashion can even be made from inside Event Service Routines. /*******@@@@@@@@ Shedule IPX Event Assumes Bx has 5h Ax has desired delay time ES:DI has a pointer to an IPX Event Control Block In the ECB, the ESR adress and Socket Number fields are initialised Return nothing Description This functionis used to shedule or re-shedule an IPX event to occur when the specified time interval expired. The interval may be less than an 18th of a second or over an hour in length. /**************************************************************************/ Cancel Event Assumes Bx has 6h ES:DI has a pointer to an ECB that is in use by IPX or the AES Returns Al has Function complete code 00h if the event was canceled FFh if the given ECB was not in use by IPX or the AES F9h if the given ECB was in use and unable to be canceled Description This function cancels the event.... /***********************/ Shedule special event Bx has 7h Ax has desired delay time ES:DI has a pointer to an special-purpose ECB (AES-ECB) In the ECB, the ESR Adress field is initialised Return: nothing Description This function is used to shedule a special-purpose... /***************************/ Get Interval Marker Assumes Bx has 8h Returns Ax has the interval marker (16-bit Unsigned integer) Description This function returns a timing marker. This marker reflect the time at which this function was called. The value is given in units equal to the length of time between any two system clock ticks ( approximately 1/18.21 of a second) This value has no relation to any real-word absolute time.. However, when it is compared with a time marker obtained at different time, the difference will yield elapsed time. ........... /***********************************************/ Get internetwork Address Assumes Bx has 9h ES:DI has a pointer to a ten-byte buffer area Returns Four-byte Network Number and six-byte Node Address in the indicated buffer Description This function allow a programm to determine the internetwork adress of the node on which it is executing. This programm-supplied buffer is filled with four-byte Network Number followed by the six-byte Node Address. Both fields in high-low order. This function is especialy useful for any application that must other nodes of its address on the internetwork. Note that this function does not return a socket number. When programm form complete tweive-byte adresses, they should append socket numbers appropriate to their application. Rellnquish Control Assumes Bx has Ah Returns Nothing Description This function should be invoked whenever the applications will "idling", waiting for external events to provide it with serious processing to perform. ............ Disconect from target Assumes BX has Bh ES:DI point to a 12-byte buffer containing an internetwork adress Returns Nothing Description This function exists as courtesy to those network communications drivers which may operate strictly on point-to-point basis at physical transport level. .................