ContentsReturn to Smalltalk Networking
Return to P1 Systems Homepage
ContentsOverview
NetInfo
NetIF
NetEvent
Development and Runtime Files
Ordering
License Agreement
PARTSNet is a set of parts for Digitalk's PARTS Workbench which provides an interface to a TCP/IP network via the Windows Sockets interface.
With PARTSNet, you can
There are three parts supplied with PARTSNet. They are:
Your network software must provide the WINSOCK.DLL or WSOCK32.DLL in order for PARTSNet to function. Most providers of TCP/IP software either provide one of these in their base product or can provide it to you upon request. Windows NT provides WSOCK32.DLL as part of the standard system.
PARTSNet
Version 1.1
Copyright (c) 1995,1998 P1 Systems Incorporated.
All Rights Reserved.
NetInfoThe NetInfo part provides access to the name translation services of Windows Sockets. Messages are available to find the Internet address associated with a host name, the host name associated with an Internet address, the port number associated with a service name, and the service name associated with a port number. Messages are provided to determine the maximum number of sockets and the maximum datagram size of the Windows Sockets implementation as well as to return the local host name and to provide error description text associated with an error code.
Because translation of host names, service names, addresses, and port numbers may require network communication to a remote name server, asynchronous techniques are used to avoid making the application unavailable for an indeterminate period of time while waiting for a response from the remote system. This is done by separating the request from the response. Typically, the PARTS message requesting a translation does not return the requested value. Instead, an event is triggered when Windows Sockets returns the value, perhaps after communication with a remote system. This allows other activities to occur in parallel with the servicing of the request. Often the translation is performed by accessing local files (usually named hosts and services) rather than by communication with a network name server. The asynchronous method is, however, used in either case.
Here is the sequence of actions which must occur when using NetInfo:
1. You must issue the startup message to NetInfo to initialize the Windows Sockets interface. This is normally done via the opened event from the application window.
2. You may now invoke any of the various messages supported by NetInfo and process the resulting events.
3. When done, use the shutdown message to release the Windows Sockets resources associated with the NetInfo object by the startup message.
Direct-editing this part changes the part name that appears beneath the icon in the PARTS Workbench.
The properties dialog for this part is shown here. There are no part-specific controls in the properties edit dialog.
The example uses NetInfo to obtain the Internet address for a host name. The Startup button issues the startup message. Successful startup produces one sound, while unsuccessful startup produces another. The Info button sends the netInfo message and the result is displayed in the text box. The >> Address>> button translates the host name to an address. Errors are displayed in the text box.
This example is contained in your PARTSNet distribution in the file NETINFOX.PAR.
NetIFAn interface to the Windows Sockets communications API is provided by the NetIF part. Establishing network communication using NetIF involves several steps, many of which may be performed automatically for you depending on how the properties of the NetIF part are set.
Windows Sockets operates asynchronously. The NetIF part's behavior reflects this in its event/message interface. Typically, messages sent to a NetIF part do not return a useful result immediately. Instead, they send a request to Windows Sockets and trigger an event when Windows Sockets has responded. This is necessary because of the indeterminate delays associated with network communications.
In order to communicate with another application using an Internet protocol, both parties must have an Internet address. Internet addresses are usually depicted as four decimal numbers separated with periods, for example: 165.227.10.128. Internet addresses usually have a hostname associated with them which is easier to remember than the four numbers. Internet addresses and hostnames are usually assigned by a central authority in an organization to prevent conflicts.
A TCP/IP-speaking system is allowed to maintain communications with multiple remote systems at once. In order to do this without getting confused, communications is said to be performed between ports on the communicating systems. Ports are designated by decimal numbers. Like hostnames for addresses, ports can be assigned service names. Here is how NetIF would show the service personnelDb on the host named hoochie: hoochie:personnelDb. Alternatively, the address or port number can be substituted for the names, perhaps resulting in a designation like: 165.227.10.128:6001.
Hostnames and service names are often maintained by TCP/IP implementations in files called hosts and services, respectively.
For two applications to establish communications, one application must attempt to connect to the other by specifying a port (or service) on which the other is listening. If it cannot be determined which application might attempt to connect first, then both applications may listen on a port known to the other. It is up to you to decide what port (and service name) you will use for your communications.
Once connected, network messages received by a NetIF part result in two triggered events, the receivedFrom: event and the received: event. They are triggered in that order. This is because a NetIF part may be simultaneously connected to multiple remote parties. By triggering the receivedFrom: event which contains the identity of the sending party before the received: event which contains the data received, the receiving application can, if necessary, establish the correct context in which to interpret the message before the data arrives.
NetIF supports five types of connections: datagram, stream, message, string, and object.
Datagram and stream correspond to the Windows Sockets definitions. Datagrams provide unguaranteed delivery of messages but require no previously established connection. Datagram message size is limited to the smaller of the maximum datagram size supported by the TCP/IP software executing at either end of the communication. Stream connections provide guaranteed sequenced delivery, require a previously established connection, and may coalesce or fragment the data transferred. That is, a stream connection may not deliver the data in the same chunks in which it was sent, although the bytes are guaranteed to be in the correct order. There is no maximum size for a stream transmission as is the case with datagrams.
NetIF message connections provide record-oriented communications over a stream connection. This allows guaranteed delivery of messages without the problems normally incurred with stream connections. That is, partial messages are never delivered, and more than a single complete message is never delivered. Message connections are likely to be most useful in communicating with a non-PARTS Visual Smalltalk application which is using the Sockets/V product.
String connections are a simplified form of message appropriate for use with the PARTS Workbench. Object connections allow passing such objects as Arrays, Sets, and Dictionaries between PARTSNet applications.
In the discussion which follows, string type connections are assumed. If datagrams are used instead, the listenOn: message and connectTo:service messages are not needed, nor will the connected: or acceptFrom: events be triggered.
Here is the sequence of actions which must occur when using NetIF:
1. You must issue the startup message to NetIF to initialize the Windows Sockets interface. This is normally done via the opened event from the application window.
2. If you plan to listen for connections from others, you must provide NetIF with the local port or service on which to listen. You can do this with the Properties Editor or in the argument to the listenOn: message. You can provide either the port number or the service name. NetIF will perform any necessary translation.
3. If you plan to connect to a listening application, you must provide the remote hostname or address and the remote service or port number. You can do this with the properties editor, in the argument to the connectTo:service: message, or, if you so specify in the properties editor, a dialog box can be displayed for the user to enter the information at run time.
4. Base further action on receipt of the accepted: message if you were listening, or the connectedTo: message if you were connecting. If an error occurs, the connectError: or acceptError: events may be triggered.
5. Assuming no errors occurred, you may now send messages using the send:to: message and receive messages via the receivedFrom: and received: events. The receivedFrom: event contains identification of the sending hostname/address:service/port. The received: event contains the received data.
6. Once operations are complete, send a close: message to the NetIF part for each connection, or use the closeAll to close all connections. Then you may send the shutdown message to release the Windows Sockets DLL.
The following events may be triggered from NetIF parts whose connection type is set to Stream, Message, String, and Object.
The following events may be triggered by NetIF parts whose connection type is set to Datagram.
The following messages may be sent to NetIF parts whose connection type is set to Stream, Message, String, and Object.
The following messages may be sent to NetIF parts whose connection type is set to Datagram.
Direct-editing this part changes the part name that appears beneath the icon in the PARTS Workbench.
The properties dialog for this part is shown here. The part-specific controls are discussed in the following paragraphs.
This is the host name or address (in n.n.n.n form) that will be used if the connect message is sent to the NetIF part and which is provided as the default in the Connect dialog box. Note that this value can be queried and changed using the defaultHost and defaultHost: messages, respectively.
This is the service name or port number that will be used if the connect message is sent to the NetIF part and which is provided as the default in the Connect dialog box. Note that this value can be queried and changed using the defaultService: and defaultService: messages, respectively.
This is the service name or port number that will be used if the listen message is sent to the NetIF part. Note that this value can be queried and changed using the defaultLocalService and defaultLocalService: messages, respectively.
If this check box is checked, NetIF immediately issues a connect message to itself after the startup message is processed. If the Connect Dialog check box is checked, a dialog box is presented to the user to allow them to specify the host and service to connect to. This relieves you of the need to send the connect message in client applications.
If this check box is checked, NetIF immediately issues a listen message to itself after the startup message is processed. This relieves you of the necessity of issuing the listen message in server applications.
If this check box is checked, a dialog is presented to the user when the connect message is sent to the NetIF part. This dialog box is shown here.
From this set of radio buttons you select the type of network connection to be used for communications. All parties to a communication must use the same type of connection. Object type connections are recommended if you will be passing objects other than strings, otherwise, String type connections are recommended for inter-communicating PARTSNet applications. To communicate with a Sockets/V application, Message type connections are provided. To communicate with non-PARTSNet or Sockets/V applications, the Stream or Datagram type connections are appropriate.
NetIF parts may be used in the same application with NetInfo and NetEvent parts. Multiple NetIF parts may be used in a single application, although this is not likely to be necessary very often.
The example server and client applications shown below allow multiple clients to connect to and exchange messages with a single server. The server keeps track of the currently connected clients in a listbox and can send a message to any connected client.
The Listen on Startup and Connect on Startup properties are set to decrease the number of links in the examples.
The NetIF part in the example server depicted above and contained in your PARTSNet distribution as NETIFXS.PAR assumes that the NetIF properties have been set for Listen on Startup. The opened event from the main window sends the startup message to the NetIF part. The resulting startupOk event sends invokes a message box which obtains its title from the main window's label and its text from a netInfo message sent to the NetIF part.
Whenever an incoming connection is accepted, the accepted: event is used to add the remote system's address to the upper listbox. When a connection is closed, the closed: event is used to remove the remote system's address from the upper listbox. In this manner, the listbox always displays the current connections.
When a message is received, the receivedFrom: event is used to select the address from which the message was received. The received: event is used to add the message text to the lower listbox.
The speaker is sounded whenever a connection is accepted or a message is received.
To send a message, select the address to which the message is to be sent by selecting it in the upper listbox. Then press the Send button. A Prompter is displayed into which you enter the message text. The send:to: message is used to send the message text to the selected address.
The aboutToClose message from the main window sends the closeAll message to the NetIF part and the closed event sends the shutdown message.
The NetIF part in the sample client depicted above and contained in your PARTSNet distribution as NETIFXC.PAR assumes that the NetIF properties have been set for Connect on Startup and Connect Dialog. The opened event from the main window sends the startup message to the NetIF part, which responds, after a successful startup, by displaying the Connect dialog. Enter the Internet address or host name and server name or port number into the dialog box and press enter to attempt a connection.
The connectedTo: event is used to display the server address in the listbox. The Send button is used to send a message as in the server example above, except that messages may only be sent to the server to which you are connected.
The receivedFrom: event is used to sound the speaker when a message is received from the server. The received: message is used to display received messages in the listbox.
The aboutToClose message from the main window sends the closeAll message to the NetIF part and the closed event sends the shutdown message. A closed: event from the NetIF part, indicating that the server has disconnected, sends the close message to the main window, terminating the application.
The above example shows a portion of an application to demonstrate how to display detailed error information. The serviceNameError: message sends the openTitle:text: message to a message box. The title text is the error code from the serviceNameError: event. The descriptive text is the result of sending the errorDescription: message to NetIF with the errorCode from serviceNameError: as the argument.
NetEventNetEvent parts allow one PARTSNet application to trigger events in other PARTSNet applications to which it is connected. You define messages for the NetEvent part using the properties editor. For each message, you specify an associated event which is to be triggered by remote NetEvent parts when the local NetEvent part processes the message. Thus, after network connectivity is established, sending a message to a local NetEvent part causes the associated event to be triggered by remote NetEvent parts.
NetEvent allows you to pass arguments by simply creating a message which supports arguments (i.e., by using colons). More than one argument may be specified in the message, in which case, the arguments beyond the first one are retrieved by the receiving application using additional NetEvent messages directed to the receiving NetEvent part.
Arguments may be of several object types, including collection types such as sets, arrays, dictionaries, and strings.
NetEvent parts optionally re-broadcast received events. This allows propagation of events even when not every NetEvent part is connected to every other NetEvent part in an application system.
Once you have defined messages and events for your NetEvent parts using the properties editor, the sequence of actions which must occur when using NetEvent is similar to that for using NetIF:
1. You must issue the startup message to NetEvent to initialize the Windows Sockets interface. This is normally done via the opened event from the application window.
2. If you plan to listen for connections from others, you must provide NetEvent with the local port or service on which to listen. You can do this with the Properties Editor, in the argument to the listenOn: message, or if you so specify in the properties editor, a dialog box can be presented for the user to enter the information at run time. You can provide either the port number or the service name. NetEvent will perform any necessary translation.
3. If you plan to connect to a listening application, you must provide the remote hostname or address and the remote service or port number. You can do this with the properties editor, in the argument to the connectTo:service: message, or, if you so specify in the properties editor, a dialog box can be displayed for the user to enter the information at run time.
4. Base further action on receipt of the accepted: message if you were listening, or the connectedTo: message if you were connecting. If an error occurs, the connectError: or acceptError: events may be triggered.
5. Assuming no errors occurred, you may now trigger events in remote systems by sending your defined messages to the NetEvent part.
6. Once operations are complete, send a close: message to the NetEvent part. Then you may send the shutdown message to release the Windows Sockets DLL.
Direct-editing this part changes the part name that appears beneath the icon in the PARTS Workbench.
The properties dialog for this part is shown here. The part-specific controls are discussed in the following paragraphs.
This is the host name or address (in n.n.n.n form) that will be used if the connect message is sent to the NetEvent part and which is provided as the default in the Connect dialog box. Note that this value can be queried and changed using the defaultHost and defaultHost: messages, respectively.
This is the service name or TCP port number that will be used if the connect message is sent to the NetEvent part and which is provided as the default in the Connect dialog box. Note that this value can be queried and changed using the defaultService: and defaultService: messages, respectively.
This is the service name or TCP port number that will be used if the listen message is sent to the NetEvent part. Note that this value can be queried and changed using the defaultLocalService and defaultLocalService: messages, respectively.
If this check box is checked, NetEvent immediately issues a connect message to itself after the startup message is processed. If the Connect Dialog check box is checked, a dialog box is presented to the user to allow them to specify the host and service to connect to. This relieves you of the need to send the connect message in client applications.
If this check box is checked, NetEvent immediately issues a listen message to itself after the startup message is processed. This relieves you of the necessity of issuing the listen message in server applications.
If this check box is checked, a dialog is presented to the user when the connect message is sent to the NetEvent part. This dialog box is shown here.
{bml cnctdlg.bmp}
If this check box is checked, the NetEvent part will re-broadcast events to all connected NetEvent parts. Events received from other network applications are not re-broadcast if this check box is not checked.
Note that events contain a unique identifier. This allows NetEvent parts to identify duplicate events. NetEvent parts will not re-trigger events when a re-broadcast of a previously triggered event is received.
A multitude of heavily interconnected re-broadcasting NetEvent parts can produce a large amount of network traffic. One strategy to reduce network traffic is to provide one or a few "hub" systems which handle re-broadcasting of events for the rest of the systems (which do not broadcast). Multiple hubs can be created to provide for the case of one hub system failing. Another strategy is to have each system connect to only a few other systems while always providing an alternate path should one system fail. In this case, all systems broadcast, but only to a small number of partners. This strategy has the disadvantage of requiring a potentially large number of transmissions for an event to propagate throughout the network.
Pressing this button displays the dialog box shown below, which allows you to define new messages and the associated event which will be triggered by connected NetEvent parts when the new message is processed. Messages can have any number of arguments. Event arguments beyond the first are accessed by the received application using the eventArgn and eventArgs messages, since events are restricted to a single argument in PARTS.
Messages and events added in this way appear in the dialog boxes presented when links are created or modified in the PARTS Workbench.
Pressing this button removes the currently selected message in the Message list box to the left and its associated event.
Selecting a message in this list box causes the associated event to be displayed in the Event text box below.
NetEvent parts may be used in the same application with NetInfo and NetIF parts. Multiple NetEvent parts may be used in a single application, although this is not likely to be necessary very often.
Note that all NetEvent parts within a distributed application should have the same messages and associated events defined for them. While this is not strictly necessary in every case, it can be very difficult to debug distributed applications when NetEvent message definitions vary between programs.
The example server and client applications shown below implement a simple message broadcasting system. Clients can send text messages (via PARTS events) to the server which then, using the re-broadcast feature of NetEvent, automatically forwards the message to all connected clients. The sender of a message does not see the message appear in the local text window because NetEvent parts do not trigger events when the initiating message was sent from within the same application. The server can also send messages, which are broadcast to all clients.
The example server depicted above (and contained in the file NETEVXS.PAR) assumes the NetEvent part properties are set to Listen on Startup and Re-broadcast Events and that the message msgFrom:text: and its associated event msgFrom: have been defined.
The opened event from the main window sends the startup event to the NetEvent part.
When a msgFrom: event is triggered, the first argument is written to the text window with the append: message. The second argument (obtained with the eventArg2 message) is appended to the first argument (now in the text window) separated by a colon and followed by a newline using the custom appendLineAfterColon: message. The appendLineAfterColon: message is defined as:
AppendLineAfterColon: text
self append: ': ',text,CR asString Lf asString.
The Send button clicked event displays a Prompter whose ok: event sends the msgFrom:text: event to the NetEvent part. The first argument is the result of the localHostName: message sent to the NetInfo part and the second argument is taken from the Prompter's ok: event.
The aboutToClose message from the main window sends the closeAll message to the NetEvent part and the closed event sends the shutdown message to the NetEvent and NetInfo parts.
The example client depicted above (and contained in the file NETEVXC.PAR) assumes the part properties are set to Connect on Startup and that the message msgFrom:text: and its associated event msgFrom: have been defined.
The only significant difference between the client and server NetEvent examples is that the client does not re-broadcast events.
The following files are required to develop programs using PARTSNet, but must not, under the terms of your license, be distributed with programs you develop with PARTSNet.
PRTSNETR.SML (PARTSNet source code)
PRTSNETW.SLL (PARTSNet workbench)
PRTSNETW.SML (PARTSNet workbench source code)
The following files are included with PARTSNet to aid you in developing your programs. You may incorporate portions of these sample programs in your programs, but you may not distribute the sample programs themselves.
NETINFOX.PAR (NetInfo example)
NETIFXS.PAR (NetIF example server)
NETIFXC.PAR (NetIF example client)
NETEVXS.PAR (NetEvent example server)
NETEVXC.PAR (NetEvent example client)
The following file is required to execute PARTSNet applications and may be distributed with your applications.
PRTSNETR.SLL (PARTSNet run-time library)
PARTSnet includes all source code for PARTSNet and Sockets/V. See the text file ORDER.FRM for ordering information and pricing.
There are no run-time fees for applications developed with PARTSNet. The run-time SLL may be distributed freely with your applications.
P1 Systems Incorporated provides 90 days of free technical support via voicemail, FAX, Internet mail and CompuServe mail.
Guarantee: PARTSNet may be returned for a full refund for any reason within 90 days if you are not fully satisfied.
VISA, MasterCard, and corporate purchase orders accepted.
PARTSNet is available from
P1 Systems Incorporated
PMB 320
1315 Madison Street
Seattle, WA 98104-3512
VoiceMail: +1 206 374-2475
FAX:+1 206 374-2475
Internet: info@p1.com
This is a legal agreement between you, the end user, and P1 Systems Incorporated (P1). Having installed the software on your computer, you have agreed to be bound by the terms of this Agreement. If you do not agree to the terms of this Agreement, do not install the software and promptly return the software and the accompanying items (including written materials and other containers) to the place you obtained them for a full refund.
Grant of License. P1 grants you (i) a non-exclusive, nontransferrable license to use one copy of the enclosed P1 software program (the "Software") on a single computer for your personal use on the understanding that a single person uses each copy, and (ii) a non-exclusive, nontransferable license to use one copy of the related written materials enclosed ("Documentation"). Purchasers of the Software are therefore licensed to use it themselves on one computer at a time, and to make a single backup copy for their own use. No other license is given. In particular, the Software may not be installed on a computer network for use by more than one person. The Software may not be rented or leased to others, and the conditions of this sale apply to the purchaser in any resale.
Limited Warranty. P1 Systems Incorporated (P1) warrants the enclosed diskettes and documentation to be free of defects in materials and workmanship for 90 days from the date of purchase. Defective products returned to P1 during this period will be replaced without charge and are subject to the original warranty. Furnishing such replacements is P1's only obligation under the terms of this sale.
Although P1 has made all efforts to ensure that the Software performs as stated in the Documentation, no representation is made and no guarantee is given regarding the Software's merchantability, performance, or its fitness for any purpose. It is sold as-is and purchasers assume all risks regarding its suitability for their purposes.
P1 is not liable for any loss of profit or other commercial damages, including but not limited to, special, incidental, consequential or other damages, including loss of data, resulting from the use of the Software.
This is the sole and exclusive statement of P1's warranty, and no one is authorized to alter it in any way either orally or in writing.
Copyright. The Software and Documentation are owned by P1 and are protected by US and International copyright laws. You may not copy the Software or Documentation, except that you may make one copy of the Software solely for backup or archival purposes. No part of the Documentation may be reproduced or transmitted in any form or by any means, electronic or mechanical, including but not limited to photocopying, without prior written permission from P1. Copying or duplicating the Documentation or any part thereof is a violation of the law.
Runtime Rights and Limitations. You have a royalty-free right to reproduce and distribute executable files created by using the Software that include the runtime environment portions of the Software (the "Runtime Files") which are identified in the Documentation as being required to execute programs. The executable you distribute must not contain any part of the development environment portions of the Software (the "Development Files") which are identified in the Documentation as being required to develop programs using the Software. You may not distribute any portion of the source code of the Software. You may not distribute executable files whose functionality is similar to that of the Software.
Governing Law. This Agreement shall be governed and construed under the laws of the State of California and subject to the exclusive jurisdiction of the courts therein.
Entire Agreement. You agree that this Agreement expresses the entire understanding between you and P1 and superscedes all other communications, oral or written, relating to the Software.