Endpoint Overview

Article Overview
Section Articles
Section Labs
Other Materials
Technical Introduction To Endpoints
Where To Go From Here
Notes

Goals

This article provides an overview for the section on endpoints as well as a brief technical overview of endpoints. The technical information is much the same as the information presented in the Overview section article Newton 2.0 Communications Overview.

Since endpoints are the fundamental interface to the Newton communications system, this section is the largest and most detailed section in the course. Its goal is to provide you with a working vocabulary of code and coding techniques as well as a conceptual map for the endpoint API.

Prerequisites

You should be an experienced NewtonScript programmer who is familiar with the Newton view system and the use of the Newton Toolkit (NTK). It is also better if you have some experience with communications programming whether on the Newton or another platform however this is not strictly necessary. Without experience with communications programming you will be taking on the double task of learning basic communications concepts as well as the Newton communication API.

Required Equipment

You must of course have a Newton and a desktop machine equipped with version 1.5 or later of the Newton Toolkit. You will need an appropriate cable to connect your desktop machine and the Newton for downloading packages from NTK. You may also need another cable and hardware (such as a modem) for running the communications code we provide as well as the code you write. NTK may be purchased from Apple and the necessary cables can usually be purchased from any store or mail order supplier which sells computer products.

Having a serial I/O PCMCIA card is also useful (but not necessary) as it makes debugging endpoint code much easier by allowing you to keep the Inspector connected while sending and receiving data. For details on this and other debugging issues see the article Debugging Endpoints.

For technical details on endpoints, the "must read" reference is the document: Newton Programmers Guide: Communications, particularly Chapters 4 and 5 (Endpoints and Built-in Communication Tools). This document is available from the Newton Technical Information web site. This section is based primarily on the information in these chapters. It is probably also a good idea to have a copy of The NewtonScript Programming Language, The Newton Programmer's Guide: System Software 2.0 and Newton Toolkit User's Guide. Finally the Q&A's Newton 2.0 document has several very important descriptions of the interactions between the Newton operating system and an endpoint. These documents are also available online at the Newton Technical Information web site.

The following is a list of the articles in this section along with a brief description of their content:

Communications and State Machines talks about implementing communications code as a state machine. This article is designed for readers who have never written a software state machine, or have never done so in implementing communications software. Since the Newton endpoint API pretty much assumes a state machine approach, this article provides an introduction to the basic concepts used by the Newton communications system.

The Endpoint Details article gives programming particulars about how to create and use endpoints while avoiding specifics for particular types of endpoints.

Endpoint Flavors describes the features and requirements of the various kinds of endpoints based on the low-level communications tools they are associated with.

The Endpoint Data Forms article describes the different types of filtering, mapping and semi-automatic data conversion options which may be applied to both incoming and outgoing data.

Other Endpoint Features is a collection of other aspects of the communications API including protoStreamingEndpoint and the Modem Setup Services.

Debugging Endpoints discusses some of the difficulties of debugging endpoints when compared to debugging other Newton code and it suggests some strategies and tools which may be used to get your communications code up and running.

The following is a list of labs in this section and what is taught in them:

Basic Modem Walkthrough takes a tour of the DTS sample code Basic Serial. It looks at a fairly simple endpoint and introduces a typical endpoint structure.

The Simple Endpoint Lab gives you hands-on experience in creating and debugging a simple serial endpoint. The code created is similar to, but simpler than Basic Modem and will form the basis for future endpoint labs.

The Asynchronous Endpoint Lab takes another look at creating state machines by using the asynchronous communications features of the 2.0 Communications system.

In the Other Features Lab protoStreamingEndpoint is used along with the Modem Setup Tool. This should give the student hands-on experience with most of the endpoint features available.

Finally, the Converting 1.x to 2.0 Lab is directed at those people who have written code for the 1.x version of the Newton Communications System who want to upgrade their code to take advantage of the 2.0 system. If you are not converting code you may still want to look at the solution code as it is an example of a working AppleTalk endpoint.

In addition to the articles and labs described above, the following materials are also available as part of this class:

The InputSpec Movie is a QuickTime movie (for both Windows and Macintosh) which gives a visual display of how InputSpec frames are used to control input to endpoints.

The 2.0 Endpoint Reference Card is a file giving a brief summary of the endpoint API for easy reference.

Endpoints are the primary API for programming communications on the Newton in NewtonScript. They provide a "virtual pipeline" for all communications. That is, they are designed as much as possible to hide the specifics of a particular communications media and, once connected, endpoint input and output code is usually the same regardless of the link protocol being used.

Endpoint code to receive data from an AppleTalk network can be identical to code to receive data through a modem, which can be identical to code to receive data over a serial line, etc. Things such as packetization-which occurs in any network protocol-are hidden from the endpoint user during sending and receiving, as are things such as flow control, error recovery, etc.

The only exceptions to this rule occur when there are specific hardware limitations that push through the endpoint API. For example, IR beaming is a half-duplex protocol (it can only be in send mode or receive mode, not both at the same time) while serial, AppleTalk, or modem communications are all full-duplex (they can be in send and receive mode at the same time).

Of course, while sending and receiving are purposefully media-independent, the connection process is necessarily tied to the link protocol being used. So for example, with AppleTalk it is necessary to specify network addresses; for modem communications, a phone number; for serial communications, speed, parity, stop bits; and so on.


The following list shows the life cycle of an endpoint:

EP:Instantiate()
EP:Bind()
EP:Connect()/EP:Listen()
EP:Output()/SetInputSpec()
EP:Disconnect()
EP:Unbind()
EP:Dispose()

EP is a fictitious reference to a NewtonScript endpoint frame

An endpoint is initially defined as a frame proto'ed from protoBasicEndpoint. This has several slots describing the settings of the endpoint and methods that may be called by the system during the course of its existence. However, such a frame is not an endpoint. That is, it describes what an endpoint might look like, but it is not a NewtonScript object. To create such an object it must first be instantiated. Note that since most objects in the Newton are views, and since the view system automatically instantiates a view object when it is opened, we usually don't see this step. But with an endpoint we must explicitly instantiate it to create an endpoint object.

Once the endpoint is instantiated, it may need to be bound to a particular address, node, etc., depending on the link protocol. An AppleTalk endpoint, for example, is bound to a node on the network. This is done by sending the endpoint the Bind() message. Note that some protocols (such as serial communications) do not have a required binding phase but you must still call Bind() (and later Unbind() ).

After binding the endpoint, the Connect() message is sent to connect through the particular low-level communications tool being used. For a remote service that is accessed through a modem endpoint, the endpoint would dial the service and establish the physical connection (but not protocol items such as logging on, supplying passwords, etc.; these are part of an ongoing dialog that the application and the service must engage in once connection is established).

The endpoint method Listen() may be used to establish a connection instead of the Connect() method if the endpoint is instantiated and ready to listen to an "offer" by the remote source. Based on the particular situation with the communications protocol, an application may either reject the connection by sending the Disconnect() message to the endpoint, or accept it with the Accept() message. Infrared connections have one side sending and the other side receiving. In this case the passive side connects by calling Listen() instead of Connect().

After connecting, the endpoint is ready to send and receive data. Sending is fairly straightforward and is done by using the Output() method. When sending data, information about the form of the data (such as that it is a string, a NewtonScript frame, etc.) is usually sent. This gives the system a description of how the data should be formatted for sending.

Receiving data is a little more complex. Incoming data is buffered by the system below the endpoint level. An application must set up a description of when it wants to get incoming data. This description is in the form of an inputSpec. For example, an inputSpec could be created which looked for the string login:, or it could be set to trigger when 200 characters were receive. To some extent it can be set to notify the endpoint of incoming data after a combination of these events (e.g., after the string login: is seen or after 100 milliseconds, whichever comes first).

In any event, when an inputSpec input condition is met, an appropriate message is sent to the endpoint. This message will be different depending on the cause of the trigger; for example, a PartialScript message will be sent if the condition causing the event is a 100-millisecond wait, while an InputScript message will be sent if a specified string has been received or character limit reached.

The InputSpec Movie is a QuickTime movie which demonstrates several of these input methods in action.

At any given time, the endpoint will have only one inputSpec active. By default, the current inputSpec will remain active until told otherwise. By chaining inputSpecs together, a communications state machine of arbitrary complexity can be created. For example, before connecting to a service, an application might set an inputSpec that looks for the string login:. Once that string is seen, a new inputSpec might be activated which looks for the string Password:. When this string arrives, an inputSpec that triggers every 100 characters or when a carriage return character is received might be activated. In this way, endpoints can be used to build a communications protocol based on expected behavior of the service.

As mentioned before, the form of the data being sent or received are usually described to the endpoint. It is possible to add filters for both incoming and outgoing data which will replace any byte with any other byte. For example, it is possible to replace the carriage return character (ASCII 0x0D) with a linefeed character (ASCII 0x0A) using this method. It is also possible to specify data conversions such as ASCII to Unicode character conversions, mask off the upper bit on characters and other such common data manipulations.

When an application is done sending and receiving data and wishes to tear down the endpoint there are several messages which must be sent to an endpoint to reset the endpoint state and then disconnect and dispose of it. The first step is to terminate any outstanding inputSpecs by sending a Cancel() message. This terminates the current inputSpec and establishes the fact that no more input will be accepted. The connection is broken by calling the Disconnect() method.

Next the Unbind() message is sent to break the address association between the endpoint and the communication tool.

Finally a Dispose() message is sent to destroy the endpoint object. Note that the endpoint may be left instantiated be disconnected if it is anticipated that it may be reconnected later in the life of the application.

For more details on endpoints, the article Endpoint Details is the logical next step.

The lab Basic Modem Walkthrough gives you a look at some sample endpoint code and is typical of the kind of thing you would normally write when doing endpoint coding.

For a "bigger picture" view of the endpoint system and how it interrelates to the other portions of the communications system, the Overview Movie shows the flow of control between different parts of the system.

For details on particular kinds of endpoints, the article Endpoint Flavors details how to define and use different links under the umbrella of the endpoint API.

To try a simple hands-on programming exercise, go to the Simple Endpoint Lab.

Of course the reference materials from Apple which are available at the Newton Technical Information web site are good places to go from here too, especially the Newton Programmer's Guide: Communications document.

In this example, EP is an arbitrary name we have give a frame which is used to define an endpoint. It would typically be the name of a slot or variable used in a NewtonScript applications.

Developer Services | Technical Information | Tools | Sample Code

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help

Copyright Apple Computer, Inc.
Maintained online by commscourse@newton.apple.com
Updated 26-Sep-96 by dcd