Endpoint Flavors
Article
Overview
Serial
Endpoints
Modem
Endpoints
Infrared
Endpoints
AppleTalk
Endpoints
Modem
Setup Service
Where
To Go From Here
Notes
Goals
This article discusses the various kinds of endpoints which are available
in the built-in endpoint system. It also covers modem setup descriptions
for situations where you want to add support for a particular modem. At
the end of this article you should have a good idea of the different endpoints
supported by the system and some of their capabilities as well as information
on how to create a modem profile and add it into the system.
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. This article assumes that you have a general knowledge
of the 2.0 endpoint API. If not, you may want to refer to the article Endpoint
Details for a thorough introduction to this API.
Required Equipment
To write Newton 2.0 endpoint code you must of course have a 2.0 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. 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.
For technical details on endpoints, the "must read" reference
is the document: Newton Programmer's Guide: Communications, particularly
Chapters 5 and 6 (Built-in Communication Tools and Modem Setup Services).
This document is available from the Newton
Technical Information web site. This article 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.
All of these documents except the Q&As are available online at the Newton
Technical Information web site. The Q&As are available from the
Q&A ftp site.
Article Sections
In the Serial Endpoints section we will review
the serial tool features available to the endpoint API. Examples of some
of the major options will be given along with a brief overview of other
options which may be used more occasionally.
The Modem Endpoints section does the same for
the Modem tool and the endpoint API for modem connections.
In the Infrared Endpoints section we will cover
the features of the built-in infrared hardware which is available from the
endpoint API. We will also touch briefly on the use of the infrared chip
as a controller for analog systems such as television or home entertainment
controllers.
The AppleTalk Endpoints section discusses how
AppleTalk is implemented under the endpoint model. This section has a code
example of using the NetChooser object to find devices on an AppleTalk network.
In the Modem Setup Service section we will
cover discuss in general terms the use of the Modem Setup Service to provide
a detailed description of a modem, its capabilities and preferences in order
to make it available to users in the Modem Preferences slip.
Overview
The purpose of this article is to give useful, programmatic descriptions
and examples of the different kinds of endpoints and the features available
in each case. However in some cases the options are so varied and the uses
fairly obscure that we will content ourselves with noting that there are
other options available. For full descriptions of these options see Chapter
5 or Chapter 6 of NPG: Communications.
Since the endpoint model is designed to be as simlar as is reasonable between
different endpoint types, it is usually the case that the specific settings
that are passed to the low-level tool associated with the endpoint are done
early on in the lifecycle of the endpoint. Thereafter the ideal is that
the same code which is used to send and receive data for one kind of endpoint
may be used for another kind of endpoint virtually without change. In reality
there are some differences which percolate up to the endpoint level which
must be addressed and there are also some uses which will require special
handling. We will give examples of some of these situations and try to point
out some of the pitfalls in using each of the different types of endpoints.
This article assumes that you have a basic understanding of the relevant
concepts for a particular use. For example in the sections on Serial and
Modem Endpoints we assume that you are familiar with such concepts as baud
rate, error correction protocols, and general telecommunications principles.
If you are not and need to use these endpoints we suggest you either get
a good book on the fundamentals or, for a "quick and dirty" introduction
you may want to see the articles available in this course: An
Introduction to Serial Communications, An
Introduction to Telecommunications and An
Introduction to AppleTalk.
Serial endpoints use the low-level serial tool to output data
through a serial port or card. The required information needed to connect
a serial endpoint includes the service definition and the I/O parameters
option to set the connection speed, stop bits, and so on.
The standard asynchronous serial endpoint built into the Newton has numerous
options. The complete description of its features may be found on pp. 5-1
to pp. 5-31 of NPG: Communications but its basic features are that
it supports full-duplex, serial connections which may use a built-in serial
chip, a PCMCIA card, external modem or even the infrared connection (but
at half-duplex only). In other words you may make serial connections with
just about any communications hardware available to the Newton.
A brief summary of the options available for serial connections is available
in the table on pp. 5-3 of NPG: Communications. Summarizing this
table, the options may be grouped as follows:
1. Hardware specifications. These include such things are speed,
parity and stop bits, hardware flow control, and hardware selection, clock
settings and chip specification. These are generally set once before making
a connection though some of them may be changed later if desired.
2. Software specifications. These include serial buffer size, software
flow control, buffer control (e.g., flushing of buffers) and statistics.
These generally affect he operation of the serial tool rather than the serial
hardware (e.g., changing the buffer size does not change any settings of
the serial controller chip but instead changes how often overruns occur
or flow-control is invoked).
3. Active use of hardware. These options are used to directly control
the hardware from the endpoint level by sending instructions directly to
the low-level communications tool. These include such things as issuing
a break, notification of hardware state changes, and control of hardware
interface lines. These are used less often but are crucial for implementing
some protocols.
One thing you should especially pay attention to is when each of the option
may be used. Some options may only be used before binding, some anytime
up until a connection is established, others only after a connection
has been established and others may be used at any time. The table on pp.
5-1 summarizes these features and when they may be used.
As this section is intended to focus on commonly used features we will give
some code samples for specific options. The following code can be used to
define a serial endpoint connected through the default hardware (the built-in
serial port) at 9600 baud with no parity, 8 data bits and 1 stop bit using
pre-defined platform constants (for more on what these setting mean, see
the article Introduction
to Serial and Modem Communications):
{
_proto:protoBasicEndpoint,
configOptions: [
{ label: kCMSAsyncSerial,
type: 'service,
opCode: opSetRequired,
result: nil, },
{ label: kCMOSerialIOParms,
type: 'option,
opCode: opSetRequired,
result: nil,
form: 'template,
data: {
arglist: [
k1StopBits, // 1 stop bit
kNoParity, // no parity bit
k8DataBits, // 8 data bits
k9600bps, ], // date rate in bps
typelist: ['struct,
'long, // stop bits
'long, // parity
'long, // data bits
'long, ], }, }, // bps
] }
Here the template in the kCMOSerialIOParms carries the relevant
information about the desired settings for the serial connection. For more
about templates and their use in setting options, see the article Endpoint
Data Forms. Note that both the service definition, which specifies the
connection as being a serial endpoint, and the IOParms option have an opCode
of opSetRequired indicating that these options must be successfully
attained or the connection will not be made. In the case of the service
specification this opCode must be used however the IOParms
may have an opCode of opSetNegotiate in which
case the low-level communications tool will get the settings closest to
what were requested when the connection is established.
For more details of possible values for the IOParms option see pp. 5-14
to 5-16 of NPG: Communications.
For debugging purposes you may want to connect the endpoint through
a PCMCIA card or other device as the NTK Inspector wants to use the built-in
port. To do this add the following option before connecting your endpoint:
{ label: kCMOSerialHWChipLoc,
type: 'option,
opCode: opSetRequired,
form: 'template,
data: {
arglist: [
kHWLocPCMCIASlot1,
0,
],
typelist: [
'struct,
['array,'char, 4],
'ulong
] } },
This specifies the first PCMCIA slot as being the location of the hardware
you wish to connect through. By doing this, if say you had a PCMCIA serial
card, you keep the built-in port free for connection with NTK.
It is not unusual to compress data before sending it as this increases the
effective throughput. The built-in serial tool has MNP compression available
and it may be specified with the following options:
{ label: kCMSMNPID,
type: 'service,
opCode: opSetRequired },
{ label: kCMOSerialIOParms,
type: 'option,
opCode: opSetNegotiate,
data { bps: k38400bps,
dataBits: k8DataBits,
stopBits: k1StopBits,
parity: kNoParity }
},
{ label: kCMOMNPCompression,
type: 'option,
opCode: opSetRequired,
data: kMNPCompressionV42bis},
{ label: kCMOMNPAllocate,
type: 'option,
opCode: opSetRequired,
data: kMNPDoAllocate},
{ label: kCMOMNPDataRate,
type: 'option,
opCode: opSetRequired,
data: k38400bps},
In this example the communication service is specified by the first option
as being serial with MNP. Next the serial parameters are set, here at a
noticeably higher baud rate (38400 versus 9600 ), next MNP compression is
turned on and uses the v42bis format. The kCMOMNPAllocate option
allocates a buffer for use by the MNP tool which vastly speeds compression.
The final option sets the internal data rate of the MNP timers. This is
necessary as due to the nature of the protocol it keeps its own clocks for
data transfers and these may be different than the settings used by the
chip. Since the default data rate for the MNP tool is 2400 bps and since
we specified a chip speed of 38400, this would effectively slow the transfer
rate to a crawl.
MNP and v42bis are industry standards.
Another option worth discussing if flow control. Flow control starts and
stops transfers based on how full the I/O buffers are getting. Essentially
one side or the other says "Stop!" when in danger of overrunning
the buffer and then issues a "Go" when ready to continue. Software
flow control does this by actually sending a special character. Hardware
flow control is built in as part of the signals sent by the serial chip.
Software flow control, while easier to implement for all hardware, is only
effective if the transfer rate is less than about 4800 bps. Otherwise by
the time the "Stop!" signal gets to the sender it's too late.
Hardware flow control has a different problem: while it's effective to quite
fast speeds, it depends on the external device supporting the hardware control
signals. If it does not, then hardware flow control cannot be used.
As a result one strategy you may want to use is to set one speed and try
and get hardware flow control but if it fails, use software flow control
and a much slower speed.
Here are examples of both flow control options:
Software flow control for output using XON/XOFF characters:
{
type: 'option,
label: kCMOOutputFlowControlParms,
opCode: opSetRequired,
form: 'template, // not needed
result: nil, // not needed; returned
data : {
arglist: [
unicodeDC1, // xonChar
unicodeDC3, // xoffChar
true, // useSoftFlowControl
nil, // useHardFlowControl
0, // returned
0, // returned
],
typelist: [
'struct,
'char, // XON character
'char, // XOFF character
'boolean, // software flow control
'boolean, // hardware flow control
'boolean, // hardware flow blocked
'boolean, // software flow blocked
]
}
}
Hardware flow control is turned on for output as follows:
{
type: 'option,
label: kCMOOutputFlowControlParms,
opCode: opSetRequired,
form: 'template, // not needed
result: nil, // not needed; returned
data : {
arglist: [
unicodeDC1, // xonChar
unicodeDC3, // xoffChar
nil, // useSoftFlowControl
true, // useHardFlowControl
0, // returned
0, // returned
],
typelist: [
'struct,
'char, // XON character
'char, // XOFF character
'boolean, // software flow control
'boolean, // hardware flow control
'boolean, // hardware flow blocked
'boolean, // software flow blocked
]
}
}
Note that these options are required so that the connection attempt
will fail if it cannot be acquired at connect time if this option is passed
in when connecting.
Finally, you may want to check the success of an option request. If it was
a required options (such as flow control option above), you may simply want
to check the result slot after the call where you use the option. If it
was a negotiable option (such as the serial parameters option in the MNP
example) you may also want to check what the result of the negotiation for
the particular feature resulted in. In this latter case you can either look
directly at the frame you passed in or you if the call was made asynchronously
you will get passed an array of current options in the completion routine.
In both cases the options will reflect the actual settings used. For more
details on this and other mechanics of using options, see the article Endpoint
Details.
As mentioned previously, there are many more serial options not described
here. You are encouraged to see Chapter 5 of NPG: Communications
for more details.
Modem endpoints are used to connect through a modem to a remote
device. They have many of the same characteristics of serial endpoints but
in addition there are modem-specific features available to them. This is
probably just as well as they typically have more potential problems since
instead of being plugged directly into a serial port of a computer, they
are usually used to connect remotely to another machine via some sort of
phone connection. However, they may also be used to connect directly to
a computer if the computer will support modem-type connections.
See the DIL example SoupDrink.
Modem endpoints have many of the same connection options such as serial
parameters to control connection speed, etc., but they also support other
connection options. The modem tool supports the v42 error correction, MNP
and v42bis compression protocols as well as fax capabilities. In addition
you can create a modem profile on the fly which can be used to connect to
a modem not profiled in the modem preferences (but see the Modem
Setup Service section below) and the built-in preferences for a particular
modem may be overridden. The list of these options is given on pp. 5-32
to 5-33 in NPG: Communications along with the phase in the endpoint
lifecycle when each of these options may be invoked.
We will give some typical code examples of modem endpoints.
As with the serial endpoint, the first step is to define the service type
as well as the connection parameters. These are almost identical to a serial
connection as shown here:
[
{ label: kCMSModemID,
type: 'service,
result: nil,
opCode: opSetRequired },
{ label: kCMOSerialIOParms,
type: 'option,
result: nil,
opCode: opSetRequired,
form: 'template,
data: {
arglist: [
k1StopBits,
kNoParity,
k8DataBits,
k38400bps, ],
typelist: ['struct,
'long,
'long,
'long,
'long, ], }, },
]
In addition, we can add MNP data compression (v42bis or MNP 5) as
we did with the serial endpoint by specifying the MNP service (kCMSMNPID)
instead of the modem service and adding the following options to the option
array:
{ label: kCMOMNPCompression,
type: 'option,
result: nil,
opCode: opSetNegotiate,
form: 'template,
data: {
arglist: [ kMNPCompressionV42bis, ],
typelist: ['struct,'ulong, ], }, },
{ label: kCMOMNPDataRate,
type: 'option,
result: nil,
opCode: opSetRequired,
form: 'template,
data: {
arglist: [ k38400bps, ],
typelist: ['struct,'ulong, ], }, },
Of course, since compression is subject to the other end supporting the
relevant protocol, you may want to check whether the compression option
was put into effect. Since some devices support v42bis, some MNP 5 and some
neither, it may be desirable to ask for both and see what you get. This
is in fact what the default is for a modem connection using the modem tool
so unless you want to override compression altogether (i.e., turn it off
entirely in order to save space), you may be better to not specify a compression
option and let the default compression .
Since all communications are subject to error (such as the Dog-Plug-Wall
syndrome), using an error correction protocol is a good idea. The modem
tool comes with v42 error correction built in which may be invoked by adding
the following option to the option array:
{ label: kCMOModemECType,
type: 'option,
opCode: opSetRequired,
data: kModemECprotocolMNP }
This sets the error correction protocol based on MNP class 4 error correction.
Other options include using the default external modem's error correction
(since modems often have error correction built into them) and the modem
tool's internal error correction (set the data field to the value kModemECInternalOnly).
If you use the modem tool's error correction you it will ignore any other
error control you request but you are sure to get it but if the modem supports
an error correction protocol the modem tool will use that instead. In other
words, if you use the internal protocol and the modem you are connecting
to has another protocol, say ARQ, then the modem tool will use the modem's
error correction protocol.
Note that in the example above, your connection attempt might fail.
Of course one of the main options you need to set for most modem connections
is the address option. This provides the telephone number you want dialed.
An address option looks like this:
{
label: kCMARouteLabel,
type: 'address,
opCode: opSetRequired,
data: {
arglist: [kPhoneNumber,
8,
"555-1212",
],
typelist: [
kStruct,
kLong,
kULong,
[kArray, kChar, 0],
]
}
}
Of course this option is usually set dynamically by using data entered
by the user or by drawing from the Preferences or Names soups. One easy
way to build this option is to use the system function MakePhoneOption
described on pp. 4.57 of NPG: Communications. An example of using
this function may be found in the DTS Sample code Basic Modem. See
the Basic Modem Walkthrough
Lab or download Basic Modem from the DTS
Sample ftp site.
There are a number of other options and capabilities available using modem
endpoints including the ability to control dialing options, fax features
available for a modem, connection type specification, throughput for a current
connection and so on. For details of these options, see Chapter 5 of NPG:
Communications. One option which we will mention but not detail here
is the modem setup option. This option allows you to specify the particular
characteristics of a modem such as its error correction capabilities, speeds
it support, cellular support, etc. Instead these issues are discussed below
in the section on the Modem Setup Service.
The modem setup option is used if you want to define such a setup "on-the-fly"
from within a Newton application. For details of the option setting, see
pp. 5-38 to 5-44 of NPG: Communications.
The built-in infrared hardware in the Newton may be used for
wireless data transfers over fairly short (less than 4 meter) distances.
While it is theoretically possible to send data for distances of up to 10
meters, in point of fact there is too much data loss at distances over 3
or 4 meters and so too much time will be spent retransmitting data to recover
from errors than is sensible. Most of the time, it is expected that such
transfers will be from Newton-to-Newton though the infrared endpoint will
support the Sharp protocol supported by such devices as Sharp OZ/IQ.
Infrared endpoints are always half-duplex (that is you can either send or
receive but cannot do both at the same time) and the protocol used is a
"guaranteed delivery" protocol. Essentially the hardware is the
same as that used in TV-VCR controllers but the infrared tool implements
a delivery protocol which frames the data, checks for errors in transmission
and retransmits lost data as necessary. Because of this the effective throughput
of infrared connections is highly variable since it depends on how often
it is necessary to retransmit that data before it is received. Thus, while
you may make a connection at 9600 bps, the effective throughput may be anywhere
from significantly less than that to the full 9600 bps.
The IR hardware
can be used in an analog fashion to control TVs, VCRs, etc.
To define an infrared connection use the following frame:
ep := {
_proto:protoBasicEndpoint,
configOptions: [
{ label: kCMSSlowIR,
type: 'service,
opCode: opSetRequired,
result: nil, },
],
}
You can specify the particular protocol used with the following option:
{
label: kCMOSlowIRProtocolType,
type: 'option,
opCode: opGetCurrent,
data: {
arglist: [
protocol,
speed
],
typelist: [ 'struct,
'ulong,
'ulong
]
}
}
where the protocol value of the arglist
may specify a Sharp protocol, the Newton 1.x protocol or the Newton 2.x
protocol. The value of speed defines the speed of the connection
which may be set to 9600, 19200 or 38400 bps.
Since IR communications is half duplex in nature, once an IR endpoint is
defined there are two possible ways to establish a connection. The first
is to be the active sender in which case you call the Connect
method as usual for full duplex protocols. In this case it is expected that
you will be sending data. The second is to call the Listen
method which says that the endpoint is waiting for an active sender to establish
a connection. As described in the article Endpoint
Details you may or may not make a Connect call asynchronously
but you will almost always make a Listen call asynchronously
as there is no telling when a connect call will come in.
When you set your Newton to "Receive beams automatically" it starts
an asynchronous Listen.
On the passive (listen) side, when a connect is made you have the opportunity
to accept the proposed connection by calling the Accept method
or to reject it by calling Disconnect. Naturally in the IR
protocol you will almost always accept an incoming connection since you
have a pretty good idea who's trying to connect.
Once a connection is made, because of the half-duplex characteristic of
the hardware, you may not output data while there is an active input spec.
Instead you must make sure you the Cancel method to stop the
current input spec before sending data otherwise you will get an error when
you call the Output method. Thus you will only call SetInputSpec
when you are ready to receive input after which you will typically wait
until the data has arrived after which if you want to send data you need
to call Cancel before calling Output. Typically
this will continue as long as you continue the dialog.
Because you can either be a sender or a receiver, it is not unusual to use
the high-level packetized data format by using the sendFlags
slot of the output spec to control when the sender is done sending data
since if the receiver sets the useEOP in the termination condition
of the input spec the receiver will not be notified of incoming data until
the sender is done sending a complete "packet" of information.
For more details on this technique, see pp. 4-16 to 4-21 of NPG: Communications
or see the article Endpoint
Details.
Note: this section assumes that you are familiar with the fundamental
concepts of AppleTalk. If you are not you may want to read the article Introduction
To AppleTalk before you try this.
AppleTalk endpoints allow the Newton to connect to an AppleTalk network
but it uses the endpoint virtual stream model to send data over an ADSP
connection. In other words, the low-level AppleTalk comm tool uses ADSP
to transfer data but as far as the NewtonScript programmer is concerned
input and output works as it does for other endpoints. Although data transfer
is done using the ADSP protocol, the low-level AppleTalk tool makes the
Name Binding Protocol (NBP) and the Zone Information Protocol (ZIP) available
in the form of a number of functions which are available once the tool has
been opened. The AppleTalk tool is automatically opened after the Bind
method is successfully called.
You can open the AppleTalk tool directly if you choose to do so.
However, before we can get to transferring data we must do the following
things:
- Define the endpoint
- Get an AppleTalk address and bind it to a name
- Open the connection as either a client or a server
To define and instantiate an AppleTalk endpoint we need to specify three
things: the service type, the AppleTalk protocol (ADSP), and the name of
an ADSP object created by the tool. This is done using the following frame:
myATalkEP := {_proto:protoBasicEndpoint
configOptions:[
{ label: kCMSAppleTalkID,
type: 'service,
opCode: opSetRequired
},
{ label: kCMSAppleTalkID,
type: 'option,
opCode: opSetRequired,
data: { arglist: ["adsp"],
typelist:[
'struct
['array, 'char, 4]
},
{ label: kCMOEndpointName,
type: 'option,
opCode: opSetRequired,
data: { arglist: [kADSPEndpoint],
typelist:[
'struct
['array, 'char, 4]
]
}
]
}
The AppleTalk address consists of an NBP (Name Binding Protocol) string
which is used to associate the node address for the Newton you wish to connect
to (or your own name if you wish to be available to be connected to) with
a name. This name has three parts, the name, the type and the zone the device
is in. If you are going to act as a server you will build your own string.
Typically you use the '*' character to indicate your local zone while the
type, is an arbitrary string of up to 31 characters which describes the
type of node you are connecting to. For example, if you were going to act
as a server you might provide a type of "NewtServer". Finally
the name of your node is another arbitrary string. You might for example
take the name of the user as the node name. The address string uses the
':' to separate the node name and the type and a '@' character to separate
the type and the zone. A fully formed address would look like this:
BillNewt:NewtServer@NewtZone
To form an address option you will probably want to use the utility function
MakeAppleTalkOption which takes a single argument of the address
string you want to use. It will produce an option frame which looks something
like this:
{
label: kCMARouteLabel,
type: 'address,
opCode: opSetRequired,
data: {
arglist: [
kNamedAppleTalkAddress, // type
kNamedAppleTalkAddress, // named addr type
kDefaultLink,
28, // length of addr str
"BillNewt:NewtServer@NewtZone",
],
typelist: [
'struct,
'long,
'long,
['array, 'char, 4],
'ulong,
['array, 'unicodeChar, 0],
]
}
}
Typically this address will be passed into the Connect
or Listen method depending on whether you are connecting to
a server or are waiting for a client to connect to you.
If you are connecting to a node on the network and you know its name, then
you can simply build the address option and call Connect. But
what if you want to allow the user to choose from many possible nodes? In
this case the ZIP and NBP functions available when the AppleTalk tool is
opened may be used, particularly NetChooser. NetChooser
is an object defined at the root level (the global base view) of the system
which puts up a slip displaying the names of all the nodes in a specified
zone. It allows users to choose among the nodes displayed and to change
zones from the current one. When a node is chosen, NetChooser
essentially calls your application back by sending it the NetworkChooserDone
message in order to give it information about the name of the node selected
and the zone it is in.
To use NetChooser you must specify NBP tuple and provide a
reference to a view which it sends a NetworkChooserDone message
to when the user selects a node from the NetChooser slip. The
NetworkChooserDone method has two arguments: a string which
is the name of the device chosen and a string which is the zone it is in.
This provides the information necessary, along with the type, to build an
address.
To put up the NetChooser slip we make the following call:
NetChooser:OpenNetChooser(zone,nbpString,
startName,doneOwner,buttonText,
headerText,lookforText);
where
zone is the zone whose nodes are first displayed (nil
causes the current zone, to be used which is usually your local zone),
nbpString is a string specifying what you're looking for (e.g., "=:NewtServer@"
for all nodes of type NewtServer)
startName is the name of the node which will be selected when the
NetChooser slip first appears
doneOwner is a reference to the "context" (usually your
base view) that the NetworkChooserDone message will be sent
to
buttonText is the text which appears in the button displayed in the
righthand corner of the slip
headerText is text used in the title at the top of the slip
lookforText is the text which shows up in the view which will display
the nodes after NetChooser is done finding the nodes it will display
For example, if we make the following NetChooser call:
GetRoot().NetChooser:OpenNetChooser(nil,
"=:LaserWriter@",nil, self, "Use printer, sir",
"Printer", "printers");
This will cause the following slip to appear:
Note that the text in the selection button is based on the buttonText
parameter and the title displayed asks the user to Select a Printer
because of the headerText argument while the node display area has
the text Looking for printers... because of the value we passed in
for the lookForText argument.
Once NetChooser finds all of the nodes of the given type in
the specified zone (in this case the current zone because of the nil
passed in for the zone argument), the following slip is displayed:
Here the Looking for printers... message has been replaced by a list
of nodes of type LaserWriter which can be scrolled using the scroller
at the right of the list. Also, the current zone name is displayed above
the Change Zone button which has appeared in the lower left corner.
When the user has selected one of the nodes listed and tapped on the Use
printer, sir button, the system sends the context (the self argument,
usually the base view of the
application which called OpenNetChooser) the message NetworkChooserDone
as follows:
NetworkChooserDone(selectionName, zoneName)
where selectionName is a string with the name of the
node selected and zoneName is the name of the zone passed as
a string. Using these the application can create an address option by combining
the selection name, node type and zone name before calling Connect.
Putting this together, we might connect using the following code to call
OpenNetChooser after defining NetworkChooserDone
method as shown below:
NetworkChooserDone := func(selection, zone)
begin
if selection then
begin
local addr := selection & ":" & vNBPtype & "@"
&
if zone then zone else "*";
local address := MakeAppleTalkOption(addr);
ep:Connect( [ address ], nil, nil);
end;
end;
GetRoot().NetChooser:OpenNetChoose(nil,"=:"&vNBPtype&"@",
nil, self,"Pick this one","Machine","Machines");
vNBPtype is a slot defining the type of device we are looking for
and NetworkChooserDone is a method defined in our base view
which makes a synchronous call to a presumably previously defined, instantiated
and bound endpoint referenced by the slot ep.
If we were putting the Newton onto the network for other devices to connect
to it, we might start an asynchronous Listen call as follows:
address:=MakeAppleTalkOption("NewtServ:"&vNBPtype&"@*");
ep:Listen( [ address ],
{ async: true,
completionScript: func(ep, options, result)
ep:MListenCompProc(options, result), });
Here we are building an explicit address with a name of NewtServ
and a type as specified in the vNBPtype slot in the local zone
and asynchronously starting a listen. When someone connects to our Newton,
our method MListenCompProc will be called.
Using the Newton as a server uses a lot of power so keep it plugged in.
One last option you may wish to specify is the size of the AppleTalk buffers.
By default these buffers will be 511 bytes in size which should work well
for low traffic rates. However if you expect to move a lot of data over
AppleTalk you may want to increase the size of the incoming and outgoing
buffers. Of course since AppleTalk will not lose packets, even if they cannot
be accepted, this is not strictly speaking necessary but for the best throughput
you should increase the buffer sizes to minimize the retransmission of packets.
This is done by adding the following options:
{ label: kCMOAppleTalkBuffer,
type: 'option,
opCode: opSetRequired,
data: {
arglist: [
kSndBuffer,
kBigOutSize, // our constant
],
typeList: ['struct,
'ulong,
'ulong, ], }, },
{ label: kCMOAppleTalkBuffer,
type: 'option,
opCode: opSetRequired,
data: {
arglist: [
kRcvBuffer,
kBigInSize, // our constant
],
typeList: ['struct,
'ulong,
'ulong, ], }, },
Beyond the NetChooser object there are functions to get lists of zones,
get the name of the current zone, get names of nodes within a zone, count
the number of items having a given NBP tuple and get their names. For details
on these more specific ZIP and NBP functions, see pp. 5-73 to pp. 5-76 of
NPG: Communications.
The Modem Setup Service is a way to expand the list of known
modems stored in the Newton's system soup. To do this you create an autoload
package where the data is taken from the package, moved into the system
soup and the package is then destroyed. The data describes the modem, its
capabilities and its preferred (or default) settings. (For more details
on the System Soup, see NPG: System, Chapter 18).
Once this information is installed in the system soup the modem settings
may be displayed and chosen by the user from the list of items in the Modem
Preferences in the In/Out Boxes. To see the list of modem preferences, tap
the information button in the lower left corner of the screen while either
the In Box or Out Box are open. From the popup list which appears, chose
Modem Prefs and you will see the following slip:
The Modem setup popup lists all the modem types currently installed
in the system soup so that adding a new modem setup description will add
the name of the modem to this popup list.
A modem setup has up to four parts:
- 1. General modem information including name, manufacturer and version
number.
- 2. A list of modem preferences such as a default configuration string
to be passed to the modem, dialing options, etc.
- 3. A list of modem characteristics in a profile section which includes
such things as whether error correction is supported and what configuration
strings are needed for to turn the error correction on, what baud rates
the modem supports, etc.
- 4. A list of fax capabilities including the speeds for sending and
receiving fax data.
This information is essentially used to construct something similar to an
endpoint option which is passed to the low-level modem tool. At instantiation
if the option frame passed in by an application does not include a modem
profile option, then the modem setup package is used to condition the modem
in its default state according to the settings in the system soup. If it
does include a modem profile option then the setup options in the system
soup are not used.
Note that these settings can change from the values originally loaded.
Once the modem is conditioned using the setup options, any options passed
in from the application which change the defaults (e.g., the connection
speed) which may be in the modem preferences. In effect, the options passed
by the application dynamically "override" the defaults set by
either the modem tool or the modem setup values.
Note that the modem setup options are applied only once, during instantiation
of the endpoint and are never thereafter referenced again unless the endpoint
is disposed of an re-instantiated. This sequence is shown in the diagram
below:
The details of the modem setup specification are given in Chapter 6 of NPG:
Communications while the DTS sample code Modem Setup has an example
of a fictitious modem setup package. This sample is available at the DTS
Sample ftp site.
When creating a project for a modem setup, remember to make the package
an autoload package.
For a basic introduction to endpoints, see the Endpoint
Overview article. For more of the specifics of programming endpoints,
see the article Endpoint Details.
For an example of a modem endpoint the Basic
Modem Walkthrough Lab looks at the details of the DTS example of a modem
endpoint. For an example of serial endpoints, try the Simple
Endpoint Lab. For an example of an AppleTalk endpoint, see the solution
code in the Converting
1.x To 2.0 Lab. For an IR endpoint see the Asynchronous
Endpoint Lab.
For more general information about modems and serial connections, see the
article Introduction
To Serial and Modem Communications. For more about telecommunications
concepts, see the article Introduction
to Telecommunications and for an overview of AppleTalk terms and concepts,
see the article Introduction
to AppleTalk.
The specifics of endpoint flavors discussed in this article may be found
in Chapters 5 and 6 of NPG: Communications which is available from
the Newton technical information
web site.
DTS Sample code may be downloaded from the DTS
Sample ftp site.
MNP stands for
Microcom Networking Protocol and defines a multi-layered "packetized"
protocol for sending and receiving data. The Newton currently provides Level
5 and v42bis compression for the serial tool. For more details on telecommunications
protocols, see the article Introduction
to Telecommunications.
The SoupDrink
example allows you to connect to a desktop machine using the modem connection
as the DILs (Desktop Integration Libraries) allow modem-type connections
between the Newton and a desktop machine. The advantage of this (as suggested
above) is the possibility of using additional features not available to
a simple serial connection such as error correction.
Since the above
option was specified as requiring MNP error correction, even though the
modem tool implements this protocol, if the external device you are connecting
to does not support it the connection attempt will fail. For this reason
you may want to make the option negotiable.
While the hardware
may be driven to send the analog signals necessary to control IR receptive
devices such as televisions, home entertainment systems, etc., it is neither
easy nor reliable. For example, when you push the channel change button
on your TV controller, since the TV cannot respond if it doesn't get the
signal, the channel-changer sends the same signal 5 times for each time
you press the button. If you think about how often you have to press the
button several times to get it to change the channel you get an idea of
its unreliability. This also explains why the "guaranteed delivery"
packetized protocol Apple uses for Newton-to-Newton communications only
works over a very limited distance. To make matters worse the IR hardware
in the Newton only supports one modulation frequency (38MHz) which does
not work for all such devices.
If you turn on
the "Receive beams automatically" in the Beam Preferences in the
In Box, the In/Out Box application issues an asynchronous Listen
call and whenever an IR connect is attempted the Listen will
complete and a connection will be established.
You may call the
global function OpenAppleTalk to open the AppleTalk tool directly
but since it is automatically called when you bind the endpoint this is
usually not necessary. However, if you want to get information about a zone
or node, before the endpoint is instantiated, say at startup time,
you will need to explicitly open it. If you do this, make sure you close
it by calling the global function CloseAppleTalk. Also, make
sure that you call CloseAppleTalk once for each time you called
OpenAppleTalk as it keeps count of the number of times the
tool was opened.
AppleTalk is a
"chatty" protocol. If a Newton is used on an AppleTalk network
as a server it will constantly be sending and receiving packets from the
Newton regardless of the amount of active data transfer going on. As a result,
even while merely waiting for a connection a lot of power will be consumed.
Thus if you are going to listen for a connection for any length of time,
you should probably plug the Newton into a more long lasting power source,
like the wall.
Since the modem
preferences slip allows the user to change settings such as modem volume,
tone vs. pulse dialing or whatever are appropriate changes for the modem,
these changes are stored in the modem preferences and effect the strings
issued to the modem during the modem setup phase.
To make a package
an autoload package select the Output Settings dialog from the Project
Settings... menu item from the Project menu. This dialog will have a
radio button for the package type for an Auto Part as shown below:
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