This Technote
discusses changes and corrections in the next generation of
Mac OS: Mac OS 9. This system follows
Mac OS 8.6
and contains several enhancements and revised features.
All developers interested in creating products compatible
with Mac OS 9 will want to review this document.
Updated: [Apr 24 2000]
Hardware Requirements
Mac OS 9 can be installed on any Macintosh that
originally shipped with a PowerPC processor that has at
least 32 megabytes of physical RAM and a minimum of 40
megabytes of logical RAM (virtual memory is set to 64 by
default if there is less than 64 megabytes of physical
RAM installed).
Mac OS 9 has been tested and qualified by Apple to run
on Apple PowerPC-based Mac OS computers. (Mac OS 9 is not
tested or qualified by Apple for use on Mac OS-compatible
computers.)
For installation on 6100, 7100, and 8100 models, the computer
must be booted from the Mac OS 9 installation CD.
Back to top
Installation
|
|
Install Mac OS 9
|
The "Install Mac OS" application program requires System 7.1.2
or later to run, allowing users to install the full CD-ROM system
installation of Mac OS 9 over System 7.1.2 or later. Users
running
Mac OS 7.5.1 or earlier are required to boot from the CD to perform
an installation.
- The installer script for Mac OS 9 supports the concept of
"Feature Sets" that allow users to select different kinds of
installations beyond "for this computer" and "universal."
These new installation types are tailored to suit the needs
of particular interest groups such as, for example, Education,
Business, or Gaming.
Back to top
|
|
Finder 9.0
|
| |
The Finder provides a graphical interface for
the user along with other Apple event-based services for
applications utilizing the file system.
|
- Adds support for copying files over 2GB in size (up
to a theoretical limit of 263 bytes in size)
and displaying information about them in Get Info
windows.
- Long unicode file names are now preserved in file
copies.
- Volumes which don't support the Desktop Manager
(typically floppy disk volumes) with large "Desktop"
files now mount much faster.
- The Finder creates an invisible folder called
"TheVolumeSettingsFolder" on each writable disk,
which it uses to keep track of information about
open window positions, desktop printers, and other
items.
- Provides some support for Carbon application bundles
(folders containing one or more support files). In this
implementation of packages, there are a few points to
keep in mind:
- When the Finder attempts to open an item inside of a
package's folder, it sends an
'odoc' event containing
a list of documents to open. The difference here is
the document list is stored in an optional parameter
with the key 'fpdl' (Finder package document
list).
- In the Finder interface, packages behave
identically to applications even though they are
stored as folders. The internal contents of packages
are hidden from the user.
- If an alias is created to an item in a package
(say, while using an earlier system version) and the
user attempts to open the alias, then it will be
passed to the package's application using an
'odoc'
event with an optional 'fpdl' parameter (even if the
application's 'BNDL' does not list the file
type).
- An Encrypt item has been added to the File menu.
When selected this item will launch the "Apple File
Security" utility, passing the selected documents to it
for encryption. Files encrypted in this way can be
decrypted by double-clicking on their icons. Note: Apple
File Security cannot encrypt a folder (even if it is a
package).
- The Mac OS 9 Finder does not allow icon positioning by way
of AppleScript for icons appearing in icon views where either the
"keep arranged" or the "snap to grid" option is turned
on. If a script attempts to set the position of an icon in such a view,
the Finder will return error code number -15274 (window wrong
type).
|
|
|
Apple Help 1.5
|
| |
Apple Help provides system-wide instructional
help services for virtually all aspects of Mac OS. The
Apple Help technology has two main components: Help Viewer
and Apple Guide. |
Apple Guide 2.5
| |
In Mac OS 9, Apple Guide is used to coach users
through sequences of commands required to perform a
task.
|
- For both versions 2.3.1 and 2.4.1 of Apple Guide, the
Gestalt
version selector for Apple Guide returns 2.3.1. For Apple Guide
2.5, the Gestalt selector 'ag_v' returns
2.5.
Help Viewer 1.5
| |
Help Viewer is a lightweight HTML rendering
application that allows users to browse online help materials conveniently.
Help Viewer 1.5 provides the following new features:
|
- The ability to search locally for Internet-based
Help content, and then launch a web browser to view it.
|
Apple Data Security 2.0
| |
Apple Data Security introduces security features
to the Mac OS. New security features include facilities
for signing and verification of file signatures, password
maintenance, and file cryptography.
|
|
|
Apple Code Signing
|
| |
Apple Code Signing is a new technology in Mac OS 9
that allows applications, plug-ins, and content to be
signed by developers. Apple Code Signing Certificates
assure your customers of your identity and the integrity
of your products. For more information, please see the
Mac OS Security and Cryptography Web
site.
|
|
|
Apple File Security
|
| |
Apple File Security provides cryptographic
facilities. Users can use this application to either
encrypt a file with a password or decrypt an encrypted file. The
Finder's Encrypt menu item is dependent upon the Apple
File Security application residing within the
Applications folder. Apple File Security does not have
the ability to compress and encrypt a folder. This
precludes it from encrypting a package.
|
|
|
Cryptographic Message Syntax (CMS)
|
| |
CMS is a high-level digital signature API. For more information
about CMS, refer to the
Cryptographic Message Syntax Standard
documentation provided by RSA Laboratories, and for information about
the APIs provided in Apple's implementation, refer to the documentation at the
Mac OS Security and Cryptography
web site.
A beta version of an API for accessing CMS has been
introduced with Mac OS 9.
|
|
|
Keychain Access 2.0
|
| |
The Keychain provides a secure repository for
passwords. After entering a master password, any of the
other passwords stored in the Keychain are automatically
available to application programs, saving the user the
need to remember multiple passwords. Keychain 2.0
supports the following features:
|
- Multiple open Keychains
- Storing cryptographic keys and certificates
- Integration with Multiple Users
|
Carbon Support in Mac OS 9
|
| |
Carbon is the set of programming interfaces for use in
Mac OS applications. Carbon
includes about 70 percent of the legacy Mac OS APIs. With
Mac OS 9
comes the first installation of the Carbon APIs. The following
sections summarize
Carbon APIs available in Mac OS 9.
|
Carbon Control Manager
| |
The Carbon Control Manager introduces some changes to existing
Control Manager APIs. These new services include: |
- New routines
GetControlID and
SetControlID have been added. These routines
allow controls to be referenced by ID number.
- A new control definition packaging model has been
introduced in which controls are stored as CFM Code Fragments
rather than as standalone code resources.
- It's now possible to write a control definition to
support contextual menus.
- Attributes have been added to control properties.
Control properties can be marked as persistent so their
data will be saved when a control is flattened.
- Six new Control Manager APIs have been introduced
that allow controls to support the drag-and-drop feature. This new
feature can be turned on either on a per-control or on
per-window basis.
Carbon Menu Manager
| |
The Carbon Menu Manager introduces some changes to existing
Menu Manager APIs. These new services include:
|
- Menus are now stored as opaque data.
- Automatic handling of the Apple Menu.
- New APIs have been added for defining custom menu definitions.
Carbon Printing Manager
| |
The Carbon Printing Manager provides an entirely new
set of APIs for applications to use for generating printed
output. These new services include:
|
- New APIs or managing virtually every aspect of the
printing process.
- Extended printer settings structures for storing more user
settings.
Carbon Scrap Manager
| |
The Carbon Scrap Manager introduces new APIs for accessing the scrap.
These new services include: |
- The ability to provide "promised" scrap data, allowing applications to
defer the creation of data until if and when it is requested. This is a
concept similar to the Drag Manager's "promised" flavor model.
Carbon Window Manager
| |
The Carbon Window Manager extends and enhances the existing
Window Manager APIs, and introduces several new and interesting
window management facilities to the Mac OS. These new
services include:
|
- Window Classes and Layering
- New APIs for defining custom windows
CarbonLib 1.0
| |
CarbonLib is a shared library that allows Carbon-based applications to
run in Mac OS 9. Carbon applications link against CarbonLib
instead of linking to
InterfaceLib, etc. as CFM-based applications do
today. |
- CarbonLib 1.0 is new for Mac OS 9.
|
Compatibility Note:
CarbonLib 1.0 with only load with Mac OS 9. It
will not load with earlier versions of the Mac OS, nor
will it load with later versions of the Mac OS.
|
CoreFoundation 1.2
| |
CoreFoundation extracts various APIs and
services from Mac OS X's Cocoa APIs and makes them
available to multiple stacks on multiple platforms using
C APIs and pure C implementation. |
- String type to provide a unified and simple way to
deal with Unicode strings. Easy ways to convert between
these and Pascal and C strings in various 8-bit encodings
are provided.
- Additional collection classes (Dictionary, Array,
Data) that, along with String, provide "property list"
functionality.
- XML support for reading and writing property
lists.
- Abstractions for Date/Time along with some
utilities.
- Preferences support for reading/writing user
preferences that can be per user and/or per app.
- Bundle APIs to manage Carbon application wrappers
containing executables and arbitrary localizable
resource files.
|
Compatibility Note:
For future compatibility, developers should begin
using these string types in their software for all
international string data. |
Summary of New Carbon APIs
| |
The following summarizes new APIs introduced
by CarbonLib 1.0 that is installed as a part of Mac OS 9.
|
- Apple event Manager
AEDesc.dataHandle is opaque
AEDesc accessors
- Alias Manager
- New APIs for resolving aliases without displaying a UI
- Appearance Manager
- Control Manager
- Custom control definition support using
ProcPtrs
instead
of code resources
- Control property attributes
ControlRecord is opaque
- Control accessors
- Control IDs
- Control definitions may now support:
- Contextual menus
- Drag Manager
- Setting the cursor
- Dialog Manager
- Editing a dialog item list
DialogRecord is opaque
- Dialog accessors
- Event Manager
- New APIs to get the current mouse position and keyboard
modifiers
- Icon Services
- List Manager
- Custom list definition support using
ProcPtrs
instead of code resources
- List accessors
- MacHelp Manager
- New context-sensitive help API that replaces Balloon
Help - not recommended for use yet in CarbonLib 1.0
- Memory Manager
- New APIs for
Ptr, Handle, and
heap validation.
- Window Manager
- Custom window definition support using
ProcPtrs
instead of code resources
- Ability to change attributes of an existing window
- Window property attributes
- Window iteration by class
WindowRecord is opaque
- Window accessors
- Menu Manager
- Custom menu definition support using
ProcPtrs
instead of code resources
- Menu property attributes
- Menu and menu item attributes
- Mass menu item enabling and disabling
CommandID-based access to menu items
- Standard font menu
MenuInfo is opaque
- Menu accessors
- QuickDraw
GrafPort, QDGlobals, and
Region are opaque
GrafPort, QDGlobals, and
Region accessors
- Resource Manager
- Resource chain manipulation APIs
- Scrap Manager
- All new API that replaces the classic Scrap API
- String Comparison
TextEdit
- Accessors for some
TextEdit low-memory
globals
- Text Utilities
|
|
|
Inside the System File
|
| |
The System file contains code and resources for
running the computer. This section describes new
features, changes, and bug fixes in the System file. The
functionality provided by the System file is always
present under Mac OS 9, even when the shift key is held
down at system startup.
|
|
ATSUI (Apple Type Services for Unicode Imaging) 1.2
| |
Unicode is a character set which encodes the
characters of many languages in a flat 16-bit number
space. ATSUI extends the QuickDraw API and makes it
possible for Mac OS applications to draw Unicode text.
ATSUI provides both low-level services for drawing
Unicode text as well as much of the high-end
typographical control previously provided by QuickDraw
GX. |
- Native support for all flavors of Postscript Type 1
fonts has been added. Type 1 font formats supported
include:
- sfnt unimaster
- sfnt multimaster
- sfnt CID (primarily 2-byte)
- LWFN + FOND unimaster
- OCF (Original composite font for double-byte scripts)
- naked CID
- Memory requirements for ATSUI have been reduced.
- Breakline is now a linguistic break based on the unicode
utilities.
- Improved performance breakline operation is faster, along with faster
layout.
- Added tab character handling.
- Many new features have been added to the APIs.
- Bug fixes.
|
Code Fragment Manager 68K (CFM-68K) 4.0
| |
The 68K Code Fragment Manager (CFM-68K) is the
68K implementation of the Code Fragment Manager. The 68K
Code Fragment Manager is the part of the Mac OS on 68K
machines that loads 680x0 code fragments into memory and
prepares them for execution. CFM-68K is not appropriate
for use on PowerPC machines. |
- Several CFM-68K fragments have been removed from the
system. As Mac OS 9 only runs on PowerPC-based systems,
these are no longer needed.
|
Communications Toolbox
| |
The Communications Toolbox provides an API for
basic communications and connection services. |
- The Communications Toolbox Resource Manager (CRM) was
reporting the incorrect maximum allowable serial port
speed. In Mac OS 9, the CRM has been revised so it reports
the correct maximum allowable port speed.
|
Device Manager
| |
The Device Manager provides a programming
interface for communications between applications and
device drivers (typically code that communicates with
particular hardware devices, although some device drivers
do not actually drive devices). |
- Calls which have an asynchronous variant (
_Control,
_Status, _Read, _Write) are now
accessible synchronously from MP tasks. To test for the availability of this
functionality, developers can use the
gestaltMPCallableAPIsAttr Gestalt
selector.
|
Dialog Manager
| |
The Dialog Manager manages user interactions
with dialogs. New features in the Dialog
Manager include: |
- Carbon applications no longer have access to a
dialog's item list handle. New routines have been added
so Carbon applications can edit items in an item
list.
|
Drag Manager
| |
The Drag Manager supports drag-and-drop operations between windows and
applications. |
|
File Manager
| |
The File Manager provides services for storing
and retrieving disk-based information. New features for
the File Manager include: |
- The HFS+ API has been introduced with this version of
the File Manager. It includes support for large files
(forks over 2GB - up to a theoretical limit of 263
bytes in size),
and long Unicode names. Named forks are supported if they
are supported by the underlying file system implementation
(none of the file systems included with Mac OS 9 support
forks beyond the resource and data forks; however, it is
possible for a FSM plug-in to implement support for this
feature).
- The maximum number of open files has been increased
to 8169.
- Parameter block calls which have an asynchronous
variant, and high-level calls that are based on such
calls, can now be made synchronously from an MP task.
Calls which are always executed synchronously, such as
PBMountVol, cannot be called from MP tasks.
- The File Manager has been revised so it is no longer possible
for malfunctioning software to accidentally overwrite the catalog
or extents overflow files on HFS and HFS Plus volumes.
- The File Manager now supports a new error code being
returned from disk drivers,
driverHardwareGoneErr (-503). Disk drivers
should return this error in response to an I/O request to
a drive whose device has been disconnected and can't be
reconnected. This is especially useful for USB disk
drivers. FireWire disk drivers should continue to use the
FireWire routine FWWaitForDeviceRePlug to
force the user to reconnect the device.
|
Compatibility Note:
(System Error 119)
It is no longer possible to access the FCB table
directly. Software that calls the PowerPC low-memory
accessor functions for the FCB table will now halt the
system with a dsMustUseFCBAccessors (119)
system error. Developers needing to access FCB data should
do so using the appropriate routines, as described in
DTS Technote TN1184, "FCBs, Now and Forever." |
|
Compatibility Note:
Developers patching the existing File Manager programming interface in
order to see all File Manager requests to a volume, will have to revise
their software to patch the HFS Plus APIs as well. |
|
File System Manager
| |
The File System Manager provides a general means
by which foreign file systems can be installed,
identified, and interfaced to the operating
system. |
- New APIs have been added which allow FSM plug-ins to quickly locate
FCBs when a large number of files have been opened.
- New APIs have been added, allowing FSM plug-ins to both validate
FCB pointers and map FCB pointers to file reference numbers.
- A new API has been added that FSM plug-ins can use for
checking permissions when using fork IDs.
- File Manager now implements a compatibility layer so
that FSM plug-ins don't have to support the new HFS Plus
API calls. As long as your FSM plug-in does not set the
kVCBFlagsHFSPlusAPIsBit in the
vcbFlags fields of the VCB, the
compatibility layer will emulate the HFS Plus call on
your volume by making one or more old-style calls to your
plug-in. If you want to support HFS Plus APIs directly,
you can prevent the emulation by setting this bit.
|
Folder Manager
| |
The Folder Manager provides facilities for
locating "special" folders (such as, for example, the
Extensions folder) without relying on the names of those
folders. This aids developers in application
localization. |
|
COMPATABILITY WARNING:
In Mac OS 8.1, 8.5, 8.5.1, and 8.6, calls to
FindFolder specifying the
kDocumentsFolderType folder with the
create parameter set to kCreateFolder
will not create the folder if the folder does not
already exist. Developers wanting to create a
documents folder can create one using the location and
name returned by
GetFolderDescriptor. |
- The Folder Manager has been revised to support
multiple users.
- A new extended version of the
FindFolder
routine has been added that accepts new flags and data
parameters, allowing for more precise control of the
FindFolder operation.
FindFolder now follows aliases to
folders.
- Notification callbacks have been added along with
other facilities for managing multiple user settings.
IdentifyFolder performance has been
improved.
- A new volume selector,
kOnAppropriateDisk, has been added. This
selector allows developers to establish the location of a
particular folder when it is possible for the folder to
be located on a number of different volumes.
|
Font Manager
| |
The Font Manager provides system-wide services
for the retrieval of glyphs for display of textual
information. |
- The maximum number of active font suitcases in the
Fonts folder has been increased from 128 to 512.
- Under Mac OS 8.6 the Font Manager was creating
incorrectly formatted FOND resources and adding them to
resource files. In Mac OS 9, the Font Manger has been
revised so that it no longer does this. Furthermore, there is an
update, Font
Manager Update 1.0, available for use with
Mac OS 8.6 that includes an extension to correct this
problem, and a utility, Font First Aid, to fix fonts
corrupted by this problem.
- A new Font Management API has been added to the Font
Manager. This is a public API for accessing and modifying
the font collection to support the basic tasks of font
management. Functionality provided by the new Font
Management API includes:
- Enumerating fonts and font families.
- Accessing information about font families, including
name, character encoding, and member fonts.
- Accessing information about fonts, including
technology, format, and name.
- Accessing font data.
- Creating and managing a basic font menu.
- Activating and deactivating fonts.
- Notifying clients of changes in the font
database.
|
Mac OS USB
| |
Mac OS USB is built into the Mac OS ROM file,
and enables USB support for those Macintosh systems that
have USB built in. The changes for v1.3 are described as
follows. |
|
Memory Manager
| |
The Memory Manager is the part of the operating
system responsible for managing memory allocation
requests. |
NewHandle was crashing when the size
parameter was a value between 0xFFFFFFE1 and
0xFFFFFFFF rather than returning NULL with
MemError returning memFullErr.
This problem has been corrected - now, for this size range,
NewHandle returns NULL and
MemError returns memFullErr.
- Memory in Memory Manager free blocks is now released with
the Virtual Memory function
ReleaseMemoryData. This can
greatly reduce
the number of disk accesses when Virtual Memory needs to handle page faults.
However, this also means that programs that attempt to use pointer or handle
data after disposing it (a programming error) will likely get garbage
data.
|
Mixed Mode Manager
| |
The Mixed Mode Manager provides services for
switching between 68k emulation and PowerPC instruction
execution environments. |
- Accelerated code resources no longer crash if they
are moved in memory after they are initialized.
|
Multitasking/Multiprocessing 2.1
| |
The Multitasking/Multiprocessing Library allows applications to perform
preemptive multiprocessing operations on PowerPC computers equipped with one
or more processors. Several new features have been added to this release of
the Multitasking/Multiprocessing Library including: |
- Parameter block-based File and Device Manager requests which have an
asynchronous variant, and high-level calls which are based on such calls,
can now be called synchronously from MP tasks. (Other file manager
and device manager routines that are always executed synchronously,
such as
PBMountVol, cannot be called from MP tasks.)
- MP tasks can now call
WakeUpProcess.
- MP tasks can now call
DTInstall.
- The MultiProcessing library now loads on all machines
where Mac OS 9 can be installed.
- Greater than 1GB RAM Support.
|
Navigation Services 2.0
| |
Navigation Services provides new Open and Save
dialogs, allowing users to locate and select files and
other resources. In Mac OS 9, Navigation
Services 2.0 is built in to the System file. Features
new to Navigation Services 2.0 include:
|
- A new function has been added which simplifies the
process of attaching a preview resource to a document
(
NavCreatePreview).
- Support has been added for Carbon application packages.
Packages appear as files to the user if the client requests
them (
kNavSupportPackages). An option is also available to
allow packages to appear as folders, allowing users navigate
into them (kNavAllowOpenPackages).
- A new option is available to turn off the bevel frame around the
custom control area (
kNavDontUseCustomFrame), and another
option prevents opened files from being added to the Recent menu
(kNavDontAddRecents).
- A new event selector notifies the client when the user has opened
the current selection (
kNavCBOpenSelection).
- File filtering has been relaxed, allowing the component signature
in the
NavTypeList to have a wild-card value
(kNavGenericSignature).
- A number of new custom control selectors have been added, allowing
the client to automate and restrict certain navigation actions
(
kNavCtlBrowserSelectAll, kNavCtlGotoParent,
kNavCtlSetActionState,
kNavCtlBrowserRedraw, kNavCtlTerminate).
|
Notification Manager
| |
The Notification Manager provides a mechanism
for programs which are not the front-most application to
notify the user of specific events. |
- The Notification Manager now displays alert
notifications using a floating window. This allows the
current application's event loop to continue running
while a Notification Manager alert is on the screen.
Rather than using the cancel button as in the older style
"modal" alerts, these new Notification Manager alerts are
dismissed by clicking in the window's close box. The new
non-blocking Notification Manager fixes both of the
problems described in TN1026, "The Notification
Manager: Problems & Fixes".
- The Notification Manager now plays custom alert
sounds (specified with the
nmSound field of
the request record) asynchronously.
- The Notification Manager no longer throws away
notification requests that were posted during early boot
time.
|
Compatibility Note:
Some applications were built to depend on the event-loop-blocking behavior
of Notification Manager alerts, and
assumed that after posting an alert notification, the
posting application would not run again until the user
had dismissed the alert. This assumption has never been correct; there has
always been a small window during which the posting application could be
activated before the alert notification was displayed. With the new
non-blocking behavior of the Notification
Manager, it becomes very easy for the user to activate
the posting application without dismissing the alert.
Applications should be aware of this possibility and
not reuse a request record before the user has
dismissed the notification. An application may also
wish to explicitly cancel an alert notification with
NMRemove when the application becomes active.
As in previous versions of the Notification
Manager, the notification response procedure will not
be called until the user dismisses the alert. If your
application reuses request records, it should always
provide a response procedure that marks a request
record as no longer in use. This will prevent your
application from reusing the request record before the
alert is dismissed. |
|
Process Manager
| |
The Process Manager shares the processor among
multiple applications.
|
- A problem in Mac OS 8.6 that could cause slower
Apple event performance has been corrected.
|
Compatibility Note:
There is no process in the system that is
guaranteed to remain operational from system startup
to system shutdown. As a result, control panels,
system extensions, and applications should not assume
that state variables belonging to other processes,
such as, for instance, a processes' A5 value, will
remain constant across calls to WaitNextEvent; and,
nor should any process assume that it is safe to
allocate persistent storage in another processes' heap
zone and expect it to remain intact across calls to
WaitNextEvent. Processes requiring persistent storage
outside of their own heap zone can allocate memory in
the system heap zone. |
|
Power Manager 2.0
| |
The Power Manager provides facilities for controlling
electrical power usage on the computer.
|
- The new Power Manager includes several new APIs that allow
for finer control over energy consumption.
|
PPC Toolbox
| |
The Program-to-Program Communications Toolbox
provides process-to-process communications facilities
both for processes running on the same machine, and for
processes running on different computers connected by
either an AppleTalk network or a TCP/IP network.
|
- The PPC Browser window now provides facilities for
selecting processes on a remote machine over TCP/IP.
Users can target a machine for display in the PPC Browser
window by providing an address in either the domain name
format or the dotted-decimal address format.
|
Compatibility Note:
Guest access is not available for PPC over TCP/IP connections. |
- A new routine has been added for canceling
outstanding list ports calls (
IPCListPorts).
The new routine IPCKillListPorts takes the
parameter block from a pending IPCListPorts
call and cancels the call immediately.
- URLs specifying the target machine for a PPC over IP connection
may specify the IP address by using either a domain name or
an IP dotted-decimal address. For example, the following are
both valid URLs for PPC over IP connections:
eppc://mymac.mycompany.com
eppc://127.76.94.105
|
Compatibility Note:
The implementation of PPC over TCP/IP listens at port number
3031 for incoming PPC over TCP/IP connections. Although it
is not possible to change the listening port number, it is
possible to specify a port number in outgoing PPC over TCP/IP
connection requests.
This ability is useful in situations where multiple hosts
share a single IP address. For example, on the outside of a
network address translator (NAT) a number of different machines
may have the same IP address, while on the inside of the NAT they
may each have a unique IP address. In these cases, it is
necessary for external clients to refer to different machines
using different port numbers instead of unique IP addresses.
The NAT itself must do the translation from port numbers to
internal IP addresses using port number 3031.
Using this same example, external clients can select a specific
target machine by specifying the machine's port number in the outgoing
PPC over TCP/IP connection by providing the port number in
the destination address. For example, the address
eppc://myhost.mycompany.com:1234 specifies
port number 1234. |
-
LocationNameRec structure has been extended to support PPC Toolbox over
TCP/IP. The new structure's definition can be found in "PPCToolbox.h" in
Universal Interfaces 3.3 and higher. A new PPCLocationKind constant
has been added (ppcXTIAddrLocation) to indicate the location field
contains an XTI address. Also, a new union member in the location field,
xtiType, has been added that holds the XTI address itself. The
XTI address is stored in the same format used by Open Transport routines (such as
OTConnect); for PPC Toolbox over TCP/IP, you can use either an IP address
(AF_INET) or a DNS address (AF_DNS).
|
COMPATABILITY NOTE:
The maximum length of the XTI address stored LocationNameRec
is 98 bytes. This restriction is required so as to not change the overall
length of the LocationNameRec structure.
This is not a problem when connecting to an IP address, because the IP
address structure (InetAddress ) is always a fixed size
(16 bytes). It is potentially a problem for DNS addresses, which can
be up to 255 characters long. If your software passes DNS addresses to
PPC Toolbox and it receives a DNS address string longer than 96 bytes
(98 minus the two-byte fAddressType field), it must resolve the DNS
address to an IP address (using OTInetStringToAddress) before
passing it to PPC Toolbox. |
The code snippet shown in Listing 3 shows how you might target an Apple
event over TCP/IP or AppleTalk by setting up the location
field of the TargetID structure appropriately. Note that
OTInitDNSAddress
is an Open Transport routine that initializes an XTI address (AF_DNS)
from a C-style string and returns the XTI address length.
TargetID target;
AEDesc targetDesc;
AppleEvent event;
AppleEvent reply;
// Set up sessionID and name fields of target as before.
if (useAppleTalk) {
// target "The Count"
target.location.locationKindSelector = ppcNBPLocation;
PLstrcpy(target.location.u.nbpEntity.objStr, "\pThe Count");
PLstrcpy(target.location.u.nbpEntity.typeStr, "\pPPCToolBox");
PLstrcpy(target.location.u.nbpEntity.zoneStr, "\p*");
} else {
// target "eppc://the-count.apple.com"
target.location.locationKindSelector = ppcXTIAddrLocation;
target.location.u.xtiType.Reserved[0] = 0;
target.location.u.xtiType.Reserved[1] = 0;
target.location.u.xtiType.Reserved[2] = 0;
target.location.u.xtiType.xtiAddrLen =
OTInitDNSAddress((DNSAddress *)&target.location.u.xtiType.xtiAddr,
"the-count.apple.com");
}
err = AECreateDesc(typeTargetID, &target,
sizeof(target), &targetDesc);
if (err == noErr) {
err = AECreateAppleEvent('syso', 'beep',
&targetDesc, kAutoGenerateReturnID,
kAnyTransactionID, &event);
}
if (err == noErr) {
err = AESend(&event, &reply,
kAENoReply, kAENormalPriority, kNoTimeOut, nil, nil);
}
|
Listing 3. Targeting and Apple event over TCP/IP.
- The PPC Toolbox can now utilize Keychain Access to
automate secure connections. This allows background-only
applications to initiate secure PPC Toolbox sessions and
to send Apple events to processes on machines requiring
authentication. In the past, the user interaction
required for authentication made it impossible for
background-only applications to establish secure
connections requiring authentication. Now, in Mac OS 9,
the PPC Toolbox routine
StartSecureSession (also used by
the Apple Event Manager) works together with Keychain
Access to allow any process to open one or more secure
sessions without any user interaction.
If there is an unlocked keychain that contains an
entry for the target machine, then a secure session can be
established without user interaction; otherwise, if a
keychain entry has not been created for the target
machine, or if one exists but the keychain containing it
is locked, then an error will be returned indicating a
user interaction error has occurred.
|
