Overview
The Connection protocol is used to communicate between the desktop and the Newton.
Newton communicates with the desktop by exchanging newton event commands. The general command structure looks like this:
'newt'
'dock'
'aaaa' // The specific command
length // the length of the following command
data // data, if any
In the commands below, all data is padded with nulls to 4 byte boundaries. The length associated with each command is the length (in bytes) of the data following the length field. All strings are C strings unless otherwise specified.
Remote query
All of the commands in this section are based on the NewtonScript query functions. Please see the Newton Programmer’s Guide for details about the functions performed by the commands. The query command returns a long representing the queries cursor. Each of the other commands take this cursor as a parameter. Entries are returned with the kDEntry command.
Newton -> Desktop Commands
kDLongData 'ldta'
kDRefResult 'ref '
Desktop -> Newton
kDQuery 'qury'
kDCursorGotoKey 'goto'
kDCursorMap 'cmap'
kDCursorEntry 'crsr'
kDCursorMove 'move'
kDCursorNext 'next'
kDCursorPrev 'prev'
kDCursorReset 'rset'
kDCursorResetToEnd 'rend'
kDCursorCountEntries 'cnt '
kDCursorWhichEnd 'whch'
kDCursorFree 'cfre'
Newton -> Desktop Detailed Commands
kDLongData 5 longs
'ldta'
length
data
Newton returns a long value. The interpretation of the data depends on the command which prompted the return of the long value.
Desktop-> Newton Detailed Commands
kDQuery 4 longs + query spec size of string size
'qury'
length
parameter frame
The parameter frame must contain a queryspec slot and may contain a soupname slot.
Performs the specified query on the current store. The query spec is a full query spec including valid test, etc. functions. Soup name is a string that’s used to find a soup in the current store to query. If the soup name is an empty string or a NILREF the query is done on the current soup. A kDLongData is returned with a cursor ID that should be used with the rest of the remote query commands.
kDCursorGotoKey 5 longs + key size
'goto'
length
cursor id
key
The entry at the specified key location is returned. Nil is returned if there is no entry with the specified key.
kDCursorEntry 5 longs
'crsr'
length
cursor id
Returns the entry at the current cursor.
kDCursorMap 5 longs + function size
'cmap'
length
cursor id
function
Applies the specified function to each of the cursor’s entries in turn and returns an array of the results. A kDRefResult is returned. See MapCursor in NPG.
kDCursorMove 6 longs
'move'
length
cursor id
count
Moves the cursor forward count entries from its current position and returns that entry. Returns nil if the cursor is moved past the last entry.
kDCursorNext 5 longs
'next'
length
cursor id
Moves the cursor to the next entry in the set of entries referenced by the cursor and returns the entry. Returns nil if the cursor is moved past the last entry.
kDCursorPrev 5 longs
'prev'
length
cursor id
Moves the cursor to the previous entry in te set of entries referenced by the cursor and returns the entry. If the cursor is moved before the first entry nil is returned..
kDCursorReset 5 longs
'rset'
length
cursor id
Resets the cursor to its initial state. A kDRes of 0 is returned.
kDCursorResetToEnd 5 longs
'rend'
length
cursor id
Resets the cursor to the rightmost entry in the valid subset. A kDRes of 0 is returned.
kDCursorCountEntries 5 longs
cnt
length
cursor id
Returns the count of the entries matching the query specification. A kDLongData is returned.
kDCursorWhichEnd 5 longs
'whch'
length
cursor id
Returns kDLongData with a 0 for unknown, 1 for start and 2 for end.
kDCursorFree 5 longs
'cfre'
length
cursor id
Disposes the cursor and returns a kDRes with a 0 or error.
Keyboard Passthrough
Desktop -> Newton
kDKeyboardChar 'kbdc'
kDKeyboardString 'kbds'
Dekktop -> Newton or Newton -> Desktop
kDStartKeyboardPassthrough 'kybd'
Desktop initiated keyboard passthrough would look like this:
Desktop Newton
kDStartKeyboardPassthrough->
<- kDStartKeyboardPassthrough
kDKeyboardString ->
kDKeyboardString ->
kDOperationCanceled -> ( from either side)
<- kDOpCanceledAck
Newton initiated keyboard passthrough would look like this:
Desktop Newton
<- kDStartKeyboardPassthrough
kDKeyboardString ->
kDKeyboardString ->
<- kDOperationCanceled
kDOpCanceledAck ->
Desktop-> Newton Detailed Commands
kDKeyboardChar 5 longs
'kbdc'
length
char
state
This command sends 1 character to the Newton for processing. The char is a 2 byte unicode character + a 2 byte state. The state is defined as follows:
Bit 1 # command key down
kDKeyboardString 4 longs + string len
'kbds'
length
"string"
This command sends a string of characters to the newton for processing. The characters are 2 byte unicode characters. If there are an odd number of characters the command should be padded, as usual.
Dekktop -> Newton or Newton -> Desktop Detailed Commands
kDStartKeyboardPassthrough 4 longs
'kybd'
length
This command is sent to enter keyboard passthrough mode. It can be followed by kDKeyboardChar, kDKeyboardString, kDHello and kDOperationComplete commands.
Misc additions
Overview
Newton -> Desktop Commands
kDDefaultStore 'dfst'
kDAppNames 'appn'
kDImportParameterSlipResult 'islr'
kDPackageInfo 'pinf'
kDSetBaseID 'base'
kDBackupIDs 'bids'
kDBackupSoupDone 'bsdn'
kDSoupNotDirty 'ndir'
kDSynchronize 'sync'
kDCallResult 'cres'
Desktop -> Newton
kDRemovePackage 'rmvp'
kDResultString 'ress'
kDSourceVersion 'sver'
kDAddEntryWithUniqueID 'auni'
kDGetPackageInfo 'gpin'
kDGetDefaultStore 'gdfs'
kDCreateDefaultSoup 'cdsp'
kDGetAppNames 'gapp'
kDRegProtocolExtension 'pext'
kDRemoveProtocolExtension 'rpex'
kDSetStoreSignature 'ssig'
kDSetSoupSignature 'ssos'
kDImportParametersSlip 'islp'
kDGetPassword 'gpwd'
kDSendSoup 'snds'
kDBackupSoup 'bksp'
kDSetStoreName 'ssna'
kDCallGlobalFunction 'cgfn'
kDCallRootMethod 'crmd'
kDSetVBOCompression 'cvbo'
kDRestorePatch 'rpat'
Desktop -> Newton or Newton -> Desktop
kDOperationDone 'opdn'
kDOperationCanceled 'opcn'
kDOpCanceledAck 'ocaa'
kDRefTest 'rtst'
kDUnknownCommand 'unkn'
Newton -> Desktop Detailed Commands
kDDefaultStore 4 longs + frame size
'dfst'
length
store frame
This command returns a store info frame describing the default store. This frame contains the same info returned for all stores by the kDStoreNames command except that it doesn’t include the store info. It contains the name, signature, total size, used size and kind.
kDAppNames 4 longs + frame size
'appn'
length
result frame
This command returns the names of the applications present on the newton. It also, optionally, returns the names of the soups associated with each application. The array looks like this:
[{name: "app name", soups: ["soup1", "soup2"]},
{name: "another app name", ...}, ...]
Some built-in names are included. “System information” includes the system and directory soups. If there are packages installed, a “Packages” item is listed. If a card is present and has a backup there will be a “Card backup” item. If there are soups that don’t have an associated application (or whose application I can’t figure out) there’s an “Other information” entry.
The soup names are optionally returned depending on the value received with kDGetAppNames.
kDImportParameterSlipResult 4 longs + result frame
'islr'
length
result
This command is sent after the user closes the slip displayed by kDImportParametersSlip. The result is a frame containing the following three slots:
{
AppList : Array of strings, // contains the strings of the items selected
// in the textlist of applications
Conflicts : "string", // Text string of labelpicker entry line
Dates : Two element array of integers // The beginning and ending // dates of the selected interval // expressed in minutes
}
If the user cancels, the result sent is a nil ref.
kDPackageInfo 4 longs + a ref
'pinf'
length
info ref
This command is sent in response to a kDGetPackageInfo command. An array is returned that contains a frame for each package with the specified name (there may be more than one package with the same name but different package id). The returned frame looks like this:
{ name: "The name passed in",
packagesize: 123,
packageid: 123,
packageversion: 1,
format: 1,
devicekind: 1,
devicenumber: 1,
deviceid: 1,
modtime: 123213213,
iscopyprotected: true,
length: 123,
safetoremove: true}
kDBackupIDs 4 longs + ids
'bids'
length # -1
ids
This command is sent in response to a kDBackupSoup command–see that command for command sequence details. The length for this command is always set to -1 indicating that the length is unknown. The ids are specified as a compressed array of 16 bit numbers. Each id should be offset by any value specified by a previous kDSetBaseID command (this is how we can specify a 32 bit value in 15 bits). Each id is a number between 0 and 0x7FFF (32767). Negative numbers specify a count of the number of entries above the previous number before the next break (non-contiguous id). The sequence is ended by a 0x8000 word. So, if the newton contains ids
0, 1, 2, 3, 4, 10, 20, 21, 30, 31, 32
the array would look like this:
0, -4, 10, 20, -1, 30, -2, 0x8000
Thus we send 8 words instead of 11 longs. Is it worth it? If there are a lot of entries it should be.
kDSetBaseID 5 longs
'base'
length
new base
This command sets a new base id for the ids sent with subsequent kDBackupIDs commands. The new base is a long which should be added to every id in all kDBackupIDs commands until a kDBackupSoupDone command is received.
kDBackupSoupDone 4 longs
'bsdn'
length
This command terminates the sequence of commands sent in response to a kDBackupSoup command.
kDSoupNotDirty 4 longs
'ndir'
length
This command is sent in response to a kDBackupSoup command if the soup is unchanged from the last backup.
kDSynchronize 4 longs
'sync'
length
This command is sent to the desktop when the user taps the Synchronize button on the newton.
kDCallResult 4 longs + ref
'cres'
length
ref
This command is sent in response to a kDCallGlobalfunction or kDCallRootMethod command. The ref is the return value from the function or method called.
kDSetVBOCompression 5 longs
'cvbo'
length
what
This command controls which VBOs are sent compressed to the desktop. VBO can always be sent compressed, never compressed or only package VBOs sent compressed.
eUncompressedVBOs # 0
eCompressedPackagesOnly # 1
eCompressedVBOs # 2
kDRestorePatch 4 longs + patch
'rpat'
length
patch
This command is used to restore the patch backed up with kDGetPatches. The newton returns a kDResult of 0 (or an error if appropriate) if the patch wasn’t installed. If the patch was installed the newton restarts.
Desktop-> Newton Detailed Commands
kDRemovePackage 4 longs + ref
'rmvp'
length
name ref
This command tells the newton to delete a package. It can be used during selective restore or any other time.
kDResultString 5 longs + string
'ress'
length
errorNumber
errorStringRef
Reports a desktop error to the Newton. The string is included since the Newton doesn’t know how to decode all the desktop errors (especially since the Mac and Windows errors are different). ErrorString is a ref.
kDSourceVersion 7 longs
'sver'
length
vers
manufacturer
machineType
enum eSourceVersion {eOnePointXData # 1, eTwoPointXData # 2};
Tells the Newton the version that the subsequent data is from. For example, if a 1.x data file is being restored the desktop would tell the Newton that version 1 data was comming. Same for importing a 1.x NTF file. Otherwise, it should indicate that 2.x data is comming. When the connection is first started the version defaults to 2.x. This information is necessary for the Newton to know whether or not it should run the conversion scripts. A kDRes command with value 0 is sent by the Newton in response to this command. This commands affects only data added to the Newton with kDAddEntry and kDAddEntryWithUniqueID commands. In particular, note that data returned by kDReturnEntry isn’t converted if it’s a different version than was set by this command.
manufacturer and machinetype tell the Newton the type of newton that’s the source of the data being restored. These are sent at the beginning of a connection as part of the Newtonname command.
kDAddEntryWithUniqueID: 5 longs + entry data
'auni'
length // length of data
data // ref
This command is sent when the PC wants to add an entry to the current soup. The entry is added with the ID specified in the data frame. If the id already exists an error is returned.
Warning! This function should only be used during a restore operation. In other situations there’s no way of knowing whether the entrie’s id is unique. If an entry is added with this command and the entry isn’t unique an error is returned.
kDGetPackageInfo: 4 longs + ref len
'gpin'
length // length of data
title ref
The package info for the specified package is returned. See the kDPackageInfo command described below Note that multiple packages could be returned because there may be multiple packages with the same title but different package ids. Note that this finds packages only in the current store.
kDGetDefaultStore: 4 longs
'gdfs'
length // # 0
This command returns info about the default store. This info is the same as the info returned by the kDGetStoreNames command (see kDStoreNames for details). The default store is the one used by LoadPackage.
kDCreateDefaultSoup 4 longs + string
'cdsp'
length
soup name (c string)
This command creates a soup on the current store. It uses a registered soupdef to create the soup meaning that the indexes, etc. are determined by the ROM. If no soupdef exists for the specified soup an error is returned. A kDResult is returned.
kDGetAppNames 5 longs
'gapp'
length // # 4
return what
This command asks the Newton to send information about the applications installed on the Newton. See the kDAppNames description above for details of the information returned. The return what parameter determine swhat information is returned. Here are the choices:
0: return names and soups for all stores
1: return names and soups for current store
2: return just names for all stores
3: return just names for current store
kDRegProtocolExtension 5 longs + function
'pext'
length
command
function
This command installs a protocol extension into the newton. The extension lasts for the length of the current connection (in other words, you have to install the extension every time you connect). The function is a newton script closure that would have to be compiled on the desktop. See the Dante Connection (ROM) API IU document for details. A kDResult with value 0 (or the error value if an error occurred) is sent to the desktop in response.
kDRemoveProtocolExtension 5 longs
'prex'
length
command
This command removes a previously installed protocol extension.
kDSetStoreSignature 5 longs
'ssig'
length
new signature
This commands sets the signature of the current store to the specified value. A kDResult with value 0 (or the error value if an error occurred) is sent to the desktop in response.
kDSetSoupSignature 5 longs
'ssos'
length
new signature
This commands sets the signature of the current soup to the specified value. A kDResult with value 0 (or the error value if an error occurred) is sent to the desktop in response.
kDImportParametersSlip 4 longs + specification frame
'islp'
length
Frame containing info to display
The following is a possible example of what would be displayed on the Newton following the kDImportParametersSlip command:
The slip will, at minimum, display 2 text string fields corresponding to the slip title and a filename. Up to 5 additional fields, plus the CloseBox, could be displayed. While the slip is displayed, “helos” are sent to the desktop. When the user taps on the “Import” button or the CloseBox, a kDImportParameterSlipResult is sent to the desktop. Each of the other 5 fields is shown if the slot defining it exists in the frame parameter.
The frame contains the following slots used to configure the display of the slip:
{
SlipTitle: "string1", //this slot is required. Text string for slip title
FileName: "string2", //this slot is required. Text of file name being // imported
AppListInfo: { Title: "string", // Text string for title field above textlist.
ListItems: Array of strings, // array of strings corresponding
to applications listed in textlist
selected: Array of indexes}, // array in indexes of items in the
listitems array to select. e.g. [1,3]
would select 1st and 3rd items
ConflictsInfo: { Text: "string", // Text string for labelpicker label
labelCommands :Array of strings }, // array of strings // corresponding to // available choices in // picker list
DatesInfo: { Title: "string1", // Text string for title field above // datedurationtextpicker
Text: "string2", // Text string for datedurationtextpicker label
startTime: num, // start time in minutes from 1/1/04 12:00 am
stopTime: num}, // stop time in minutes from 1/1/04 12:00 am
ImportInfo: { Title: "String" , // This slot is required. Text string for button
ImportParametersDoneScript: function object } // function object // to call after button is tapped
}
kDGetPassword 4 longs + string
'gpwd'
length
string ref
This command displays the password slip to let the user enter a password. The string is displayed as the title of the slip. A kDPassword command is returned.
kDSendSoup 4 longs
'snds'
length
This command requests that all of the entries in a soup be returned to the desktop. The newton responds with a series of kDEntry commands for all the entries in the current soup followed by a kDBackupSoupDone command. All of the entries are sent without any request from the desktop (in other words, a series of commands is sent). The process can be interrupted by the desktop by sending a kDOperationCanceled command. The cancel will be detected between entries. The kDEntry commands are sent exactly as if they had been requested by a kDReturnEntry command (they are long padded).
kDBackupSoup 4 longs
'bksp'
length # 4
last unique id
This command is used to backup a soup. The result is a series of commands that includes all entries changed since the last sync time (set by a previous command), all entries with a uniqeu ID greater than the one specified, and the unique ids of all other entries to be used to determine if any entries were deleted. The changed entries are sent with kDEntry commands. The unique ids are sent with a kDBackupIDs command. A kDBackupSoupDone command finishes the sequence. If there are any IDs > 0x7FFF there could also be a kDSetBaseID command. The changed entries and unique ids are sent in unique id sequence. The newton checks for kDOperationCanceled commands occasionally. If the soup hasn’t been changed since the last backup a kDSoupNotDirty command is sent instead of the ids. A typical sequence could look like this:
Desktop Newton
kDBackupSoup ->
<- kDBackupIDs
<- kDEntry
<- kDEntry
<- kDBackupIDs
<- kDEntry
<- kDSetBaseID
<- kDBackupIDs
<- kDBackupSoupDone
See the definition of the other commands for details.
kDSetStoreName 4 longs + ref
'ssna'
length
name ref
This command requests that the name of the current store be set to the specified name.
kDCallGlobalFunction 4 longs + function name + args
'cgfn'
length
function name symbol
args array
This command asks the newton to call the specified function and return it’s result. This function must be a global function. The return value from the function is sent to the desktop with a kDCallResult command.
kDCallRootMethod 4 longs + method name + args
'crmd'
length
method name symbol
args array
This command asks the newton to call the specified root method. The return value from the method is sent to the desktop with a kDCallResult command.
Desktop -> Newton or Newton -> Desktop Detailed Commands
kDOperationDone 4 longs
'opdn'
length // # 0
This command is sent when an operation is completed. It’t only sent in situations where there might be some ambiguity. Currently, there are two situations where this is sent. When the desktop finishes a restore it sends this command. When a sync is finished and there are no sync results (conflicts) to send to the newton the desktop sends this command.
kDOperationCanceled 4 longs
'opcn'
length // # 0
This command is sent when the user cancels an operation. Usually no action is required on the receivers part exept to return to the “ready” state.
kDOpCanceledAck 4 longs
'ocaa'
length // # 0
This command is sent in response to a kDOperationCanceled.
kDRefTest 4 longs + ref
'rtst'
length
object
This command is first sent from the desktop to the Newton. The newton immediately echos the object back to the desktop. The object can be any newtonscript object (anything that can be sent through the object read/write).
This command can also be sent with no ref attached. If the length is 0 the command is echoed back to the desktop with no ref included.
kDUnknownCommand 4 longs + ref
'unkn'
length
bad command
This command is sent when a message is received that is unknown. When the desktop receives this command it can either install a protocol extension and try again or return an error to the Newton. If the built-in Newton code receives this command it always signals an error. The bad command parameter is the 4 char command that wasn’t recognized. The data is not returned.
Starting a session
2.0 Newton supports a new set of protocols to enhance the connection capabilities. However, since it’s desirable to also support package downloading from NPI, NTK 1.0 and Connection 2.0 the ROMs will also support the old protocol for downloading packages. To make this work the 2.0 ROMs will pretend that they are talking the old protocol when they send the kDRequestToDock message. If a new connection (or other app) is on the other end the protocol will be negotiated up to the current version. Only package loading is supported with the old protocol.
Newton -> Desktop Commands
kDPassword 'pass' // data # encrypted key
kDNewtonName 'name'
kDNewtonInfo 'ninf'
Desktop -> Newton Commands
kDInitiateDocking 'dock' // Ask Newton to start docking process
kDWhichIcons 'wicn' // optional to define which icons are shown
Examples
When a 2.0 ROM Newton is communicating with a 3.0 Connection the session would start like this:
Desktop Newton
<- kDRequestToDock
kDInitiateDocking ->
<- kDNewtonName
kDDesktopInfo ->
<- kDNewtonInfo
kDWhichIcons -> // optional
<- kDResult
kDSetTimeout ->
<- kDPassword
kDPassword ->
If the password sent from the Newton is wrong it would look like this instead. The password exchange can occurr up to 3 times before the desktop gives up.
<- kDPassword
kDPWWrong ->
<- kDPassword
kDPWWrong ->
<- kDPassword
kDPassword ->
If the password sent from the Desktop is wrong the Newton signals an error immediately.
<- kDPassword
kDPassword ->
<- kDResult
If the desktop decides that the Newton has had enough guesses a kDResult can be sent instead of a kDPWWrong. A kDBadPassword error should be specified.
No matter what the intent of the desktop or the Newton, these commands must always start a session (the desktop can substitute a kDResult for the kDSetTimeout if it doesn’t want to set the timeout).
If no password has been specied, the key is returned unencrypted.
When a 2.0 ROM Newton is communicating with NPI 1.0, NTK 1.0 or 2.0 Connection the session would look like this:
Desktop Newton
<- kDRequestToDock
kDInitiateDocking -> // session type must be loadpackage
<- kDNewtonName
kDSetTimeout ->
<- kDResult
kDLoadPackage ->
<- kDResult
kDDisconnect ->
Newton -> Desktop Detailed Commands
kDPassword: 4 longs + key
'pass'
length
encrypted Key
This command returns the key received in the initiateDocking message encrypted using the password.
kDNewtonInfo 1 long + key
'ninf'
length
protocol version
encrypted key // 2 longs
This command is used to negotiate the real protocol version. See kDDesktopInfo below for more info. The password key is used as part of the password verification.
kDNewtonName 4 longs + version info + name
'name'
length
version info
name
This command is sent in response to a correct kDInitiateDocking command from the docker. The Newton’s name is used to locate the proper synchronize file. The version info includes things like machine type (e.g. J1), ROM version, etc. Here’s the full list of what the version info includes (all are longs):
length of version info in bytes
newtonUniqueID - a number uniquely identifying the newton
manufacturer id
machine type
rom version
rom stage
ram size
screen height
screen width
system update version
Newton object system version
signature of internal store
vertical screen resolution
horizontal screen resolution
screen depth
The version info is followed by the name of the Newton sent as a Unicode string including the terminating zeros at the end. The string is padded to an even 4 bytes by adding zeros as necessary (the padding bytes are not included in the length sent as part of the command header).
Desktop-> Newton Detailed Commands
kDDesktopInfo
'dinf'
length
protocol version
desktopType // 0 for Mac, 1 for Windows
encrypted key // 2 longs
session type
allowSelectiveSync // 0 # no, 1 # yes
desktopApps // ref
This command is used to negotiate the real protocol version. The protocol version sent with the kDRequestToDock command is now fixed at version 9 (the version used by the 1.0 ROMs) so we can support package loading with NPI 1.0, Connection 2.0 and NTK 1.0. Connection 3.0 will send this command with the real protocol version it wants to use to talk to the Newton. The Newton will respond with a number equal to or lower than the number sent to it by the desktop. The desktop can then decide whether it can talk the specified protocol or not.
The desktop type is a long that identifies the senderÇ0 for the Mac and 1 for Windows. The password key is used as part of the password verification.
Session type will be the real session type and should override what was sent in kDInitiateDocking. In fact, it will either be the same as was sent in kDInitiateDocking or “settingUp” to indicate that altho the desktop has accepted a connection, the user has not yet specified an operation.
AllowSelectivesync is a boolean. The desktop should say no when the user hasn’t yet done a full sync and, therefore, can’t do a selective sync.
desktopApps is an array of frames that describes who the Newton is talking with. Each frame in the array looks like this:
{name: "Newton Backup Utility", id: 1, version: 1}
There might be more than one item in the array if the Newton is connecting with a DIL app. The built-in Connection app expects 1 item in the array that has id:
1: NBU
2: NCU
It won’t allow connection with any other id. NCK 2.0, NTK and NPI use old revs of the protocol and aren’t considered here.
kDWhichIcons 5 longs
'wicn'
length
iconMask
This command is used to customize the set of icons shown on the Newton. The iconMask is a long that indicates which icons should be shown. For example, to show all icons you would use this:
kBackupIcon + kSyncIcon + kInstallIcon + kRestoreIcon + kImportIcon + kKeyboardIcon
Where kBackupIcon # 1
kRestoreIcon # 2
kInstallIcon # 4
kImportIcon # 8
kSyncIcon # 16
kKeyboardIcon # 32
Sync and Selective Sync
Newton -> Desktop Commands
kDRequestToSync 'ssyn'
kDSyncOptions 'sopt'
Desktop -> Newton Commands
kDGetSyncOptions 'gsyn'
kDSyncResults 'sres'
kDSetStoreGetNames 'ssgn'
kDSetSoupGetInfo 'ssgi'
kDGetChangedIndex 'cidx'
kDGetChangedInfo 'cinf'
Examples
After the session is started (see above) these commands would be sent.
Desktop Newton
<- kDRequestToSync
kDGetSyncOptions ->
<- kDSyncOptions
kDLastSyncTime -> // This ones fake just to get the newton time
<- kDCurrentTime
kDSetCurrentStore ->
<- kDResult
kDLastSyncTIme ->
<- kDCurrentTime
The following would appear only if syncing system info:
kDGetPatches ->
<- kDPatches
The following would appear only if syncing packages:
kDGetPackageIDs ->
<- kDPackageIDList
kDBackupPackages ->
<- kDPackage
kDBackupPackages ->
<- kDPackage
kDBackupPackages ->
<- kDResult
Note that the above only syncs 1.x style packages on locked 1.x cards. To complete the package sync the packages soup should also by synced.
The sync would continue like this:
kDSetSoupGetInfo ->
<- kDSoupInfo
kDLastSyncTIme ->
<- kDCurrentTime
kDGetSoupIDs ->
<- kDSoupIDs
kdGetChangedIDs ->
<- kDChangedIDs
kDDeleteEntries ->
<- kDResult
kDAddEntry ->
<- kDAddedID
kDReturnEntry ->
<- kDEntry
Repeat the above for each store and soup followed by:
kDOperationComplete ->
Optionally the desktop could send this instead of the operation complete:
kDSyncResults ->
Newton -> Desktop Detailed Commands
kDRequestToSync 4 longs
'ssyn'
length // # 0
This command is sent when the Newton wants to start a sync operation.
kDSyncOptions 4 longs + frame length
'ssyn'
length // length of data
frame of info
This command is sent whenever the user on the Newton has selected selective sync. The frame sent completely specifies which information is to be snychrnoized.
{ packages: TRUEREF,
syncAll: TRUEREF,
stores: [{store info}, {store info}]}
Each store frame in the stores array contains the same information returned by the kDStoreNames command with the addition of soup information. It looks like this:
{Name: "",
signature: 1234,
totalsize: 1234,
usedsize: 1234,
kind: "",
soups: [soup names],
signatures: [soup signatures]
info: {store info frame},
}
If the user has specified to sync all information the frame will look the same except there won’t be a soups slot–all soups are assumed.
Note that the user can specify which stores to sync while specifying that all soups should be synced.
If the user specifies that packages should be synced the packages flag will be true and the packages soup will be specified in the store frame(s).
Desktop-> Newton Detailed Commands
kDGetSyncOptions 4 longs
'gsyn'
length // # 0
This command is sent when the desktop wants to get the selective sync or selective restore info from the Newton.
kDSyncResults 4 longs + array
'sres'
length
results array
This command can optionally be sent at the end of synchronization. If it is sent, the results are displayed on the Newton. The array looks like this:
{{"store name", restored, "soup name", count, "soup name" count],
["store name", restored, ...}}
Restored is true if the desktop detected that the newton had been restore to since the last sync. Count is the number of conflicting entries that were found for each soup. Soups are only in the list if they had a conflict. When a conflict is detected, the newton version is saved and the desktop version is moved to the archive file.
kDSetStoreGetNames 4 longs + frame
'ssgn'
length
store frame
This command is the same as kDSetCurrentStore except that it returns the names of the soups on the stores as if you’d send a kDGetSoupNames command. It sets the current store on the Newton. A store frame is sent to uniquely identify the store to be set:
{name: "foo",
kind: "bar",
signature: 1234,
info: {<info frame>} // This one is optional
}
A kDSoupNames is sent by the newton in response.
kDSetSoupGetInfo 4 longs + c string length
'ssgi'
length
soup name // C string
This command is like a combination of kDSetCurrentSoup and kDGetChangedInfo. It sets the current soup–see kDSetCurrentSoup for details. A kDSoupInfo or kDRes command is sent by the newton in response.
kDGetChangedIndex 4 longs
'cidx'
length
This command is like kDGetIndexDescription except that it only returns the index description if it has been changed since the time set by the kDLastSyncTIme command. If the index hasn’t changed a kDRes with 0 is returned.
kDGetChangedInfo 4 longs
'cinf'
length
This command is like kDGetSoupInfo except that it only returns the soup info if it has been changed since the time set by the kDLastSyncTIme command. If the info hasn’t changed a kDRes with 0 is returned.
File browsing
File browsing will use the same protocol described above with the following additions. For synchronize, the process is completely driven from the desktop side. For file browsing/importing, however, the process is driven from the Newton.
Newton -> Desktop Commands
kDRequestToBrowse 'rtbr'
kDGetDevices 'gdev' // Windows only
kDGetDefaultPath 'dpth' // Get the starting path
kDGetFilesAndFolders 'gfil' // Ask the desktop for files and folders
kDSetPath 'spth'
kDGetFileInfo 'gfin'
kDInternalStore 'isto'
kDResolveAlias 'rali'
kDGetFilters 'gflt' // Windows only
kDSetFilter 'sflt' // Windows only
kDSetDrive 'sdrv' // Windows only
Desktop -> Newton
kDDevices 'devs' // Windows only
kDFilters 'filt' // Windows only
kDPath 'path'
kDFilesAndFolders 'file' // frame of info about files and folders
kDFileInfo 'finf'
kDGetInternalStore 'gist'
kDAliasResolved 'alir'
Examples
After the session has started (see above) these commands would be sent:
Desktop Newton
<- kDRequestToBrowse
kDGetInternalStore -> // optional
<- kDInternalStore // optional
kDResult ->
<- kDGetDevices // Only for Windows
kDDevices -> // Only for Windows
<- kDGetFilters // Windows only
kDFilters -> // Windows only
<- kDGetDefaultPath
kDPath ->
<- kDGetFilesAndFolders
kDFilesAndFolders->
Note that we must start the transaction with a requestToDock to force 1.0 and 2.0 versions of Connection to display the correct message.
When the user changes the path by tapping on a folder, picking a new level from the path popup, or picking a new drive on the drive popup:
<- kDSetPath
kDFilesAndFolders->
When the user changes the drive by picking a drive on the drive popup (Windows only), the desktop will change the drive and set the directory to the current directory for that drive, and return the new path to the newton:
<- kDSetDrive
kDPath ->
<- kDGetFilesAndFolders
kDFilesAndFolders->
If the folder is an alias, it’s like this (Mac only):
<- kDSetPath
kDPath ->
<- kDGetFilesAndFolders
kDFilesAndFolders->
When the user taps on the File Info button:
<- kDGetFileInfo
kDFileInfo ->
If the selected item is an alias (Mac only), before doing import, getfileinfo, or setpath:
<- kDResolveAlias // name of alias
kDAliasResolved -> // 0 or 1, 0 # can't resolve
If the Windows user picks a new filter from the list:
<- kDSetFilter
kDFilesAndFolders->
Newton -> Desktop Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDRequestToBrowse 4 longs + length of file types
'rtbr'
length
file types
This command is sent to a desktop that the Newton wishes to browse files on. File types can be ‘import, ‘packages, ‘syncFiles or an array of strings to use for filtering.
kDGetDevices 4 longs
'gdev'
length // 0
This command asks the desktop system to return an array of device names. This is only used for the windows platform.
kDGetDefaultPath 4 longs
'dpth'
length // 0
This commands requests the desktop system to return the default path. This is the list that goes in the folder popup for the Mac and in the directories list for Windows.
kDGetFilesAndFolders 4 longs
'gfil'
length // 0
This command requests that the desktop system return the files and folders necessary to open a standard file like dialog.
kDSetPath 4 longs + array
'spth'
length
array of strings
This command tells the desktop that the user has changed the path. The desktop responds with a new list of files and folders. The path is sent as an array of strings rather than an array of frames as all of the other commands are for performance reasons. For the Mac, the array would be something like:
["Desktop",{Name:"My hard disk", whichVol:0}, "Business"]
to set the path to “My hard disk:business:”. “Desktop” will always be at the start of the list, since that’s the way Standard File works. So if the user wanted to set the path to somewhere in the Desktop Folder he would send something like
["Desktop",{Name:"Business", whichVol:-1}] to set the path to "My hard disk:Desktop Folder:business:"
The second item in the array, will always be a frame instead of a string and will contain an additional slot “whichvol” to indicate to the desktop whether that item is a name of a volume or a folder in the Desktop Folder and if so it’s volRefNum.
For Windows the array would be something like:
["c:\", "business"]
to set the path to “c:\business.”
kDSetDrive 4 longs + string
'sdrv'
length
drive string
This command asks the desktop to change the drive on the desktop and set the directory to the current directory for that drive. The string contains the drive letter followed by a colon e.g. “C:”.
kDGetFileInfo 4 longs + string
'gfin'
length
filename string
This command asks the desktop to return info about the specified file. See kDFileInfo for info about what’s returned.
If the selected item is at the Desktop level, a frame {Name:“Business”, whichVol:-1} will be sent instead of the string to indicate the volRefNum for the file.
kDInternalStore 4 longs + frame
'isto'
length
store frame
This command returns information about the internal store. The info is in the form of a frame that looks like this:
{
Name: "Internal",
signature: 1234,
totalsize: 1234,
usedsize: 1234,
kind: "Internal",
}
This is the same frame returned by kDStoreNames except that the store info isn’t returned.
kDResolveAlias 4 longs
'rali'
length // # 0
kDGetFilters 4 longs
'gflt'
length // # 0
This command asks the desktop to send a list of filters to display in the windows file browser. A kDFilters command is expected in response.
kDSetFilter 5 longs
'sflt'
length
index
This command changes the current filter being used. A kDFilesAndFolders command is expected in return. The index is a long indicating which item in the filters array sent from the desktop should be used as the current filter. Index is 0 based.
Desktop-> Newton Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDDevices 4 longs + length of array
'devs'
length
array
This command returns an array of frames describing devices. These are the devices which will appear in the devices popup in the Windows file browsing dialog. Each frame in the array should look like this:
{
name: "c:mydisk",
disktype: 1
}
where (floppy # 0, hardDrive # 1, cdRom # 2, netDrive # 3)
The icon is displayed in the popup. This may not be possible in which case this slot will be optional.
kDFilters 4 longs + array length
'filt'
length
filter array
This command returns an array of filters to the newton. It’s sent in response to a kDGetFilters command. The filter should be an array of strings which are displayed in the filter popup. If the filter array is nil no popup is displayed.
kDPath 4 longs + length of array
'path'
length
folder array
This command returns the initial strings for the folder popup in the Mac version of the window and for the directories list in the Windows version. It is also returned after the user taps on a folder alias. In this case the path must be changed to reflect the new location. Each element of the array is a frame that takes this form:
{
name: "my hard disk",
type: disk,
disktype: harddrive,
whichVol: 0, // Optional - see below
}
The possible values for type are (desktop # 0, file # 1, folder # 2, disk # 3). If the type is disk, there is an additional slot disktype with the values (floppy # 0, hardDrive # 1, cdRom # 2, netDrive # 3). Finally, for the second frame in the array i.e. the one after Desktop, there will be an additional slot whichvol, which will be a 0 if the item is disk or a volRefNum if the item is a folder on the desktop.
For example, the Mac might send:
[
{name: "desktop", type: desktop},
{name: "my hard disk", type: disk, disktype: harddrive, whichvol: 0},
{name: "business", type: folder}
]
or for some folder on the desktop it it might send:
[
{name: "desktop", type: desktop},
{name: "business", type: folder, whichvol: -1},
{name: "my folder", type: folder}
]
for Windows it might be:
[
{name: "c:\", type: 'folder},
{name: "business", type: 'folder}
]
kDFilesAndFolders 4 longs + length of array
'file'
length
file/folder array // array is described below
This command returns an array of information that’s used to display a standard file like dialog box on the Newton. Each element of the array is a frame describing one file, folder or device. The individual frame would look like this:
{
name: "whatever",
type: kFolder,
disktype: 0, // optional if type # disk
whichVol: 0, // optional if name is on the desktop
alias: nil, // optional if it's an alias
}
The possible values for type are desktop, file, folder or disk (0, 1, 2, 3). The frames should be in the order in the array that they are to be displayed in on the Newton. For example, the array might look like this:
[
{name: "Applications", type: kFolder},
{name: "important info", type: kFile},
{name: "System", type: kFolder}
]
If the type is a disk, then the frame will have an additional slot disktype with the values (floppy # 0, hardDrive # 1, cdRom # 2, netDrive # 3). Also, if the current location is the desktop, there is an additional slot whichvol to indicate the location of the inidvidual files, folders and disks with the values 0 for disks and a negative number for the volRefNum for files and folders on the desktop.
If the item is an alias there is an alias slot. The existence of this slot indicates that the item is an alias.
kDFileInfo 4 longs + frame length
'finf'
length
frame of info
This command is sent in response to a kDGetFileInfo command. It returns a frame that looks like this:
{
kind: "Microsoft Word document",
size:20480,
created: 3921837,
modified: 3434923,
icon: <binary object of icon>,
path: "hd:files:another folder:"
}
:kind is a description of the file. :size is the number of bytes (actual, not the amount used on the disk). :create is the creation date in newton date format. :modified is the modification date of the file. :icon is an icon to display. This is optional. :path is the “user understandable” path description
kDGetInternalStore 4 longs
'gist'
length // # 0
This command requests the newton to return info about the internal store. The result is described with the KDInternalStore command.
kDAliasResolved 5 longs
'alir'
length // # 4
0 or 1
This command is sent by the desktop in response to the kDResolveAlias command. If the value is 0, the alias can’t be resolved. If the data is 1 (or non-zero) the alias can be resolved.
File importing
File importing uses the file browsing interface described above. After the user taps the import button, the following commands are used.
Newton -> Desktop Commands
kDImportFile 'impt'
kDSetTranslator 'tran'
Desktop -> Newton
kDTranslatorList 'trnl'
kDImporting 'dimp'
kDSoupsChanged 'schg'
kDSetStoreToDefault 'sdef'
Examples
When the user taps the import button:
Desktop Newton
<- kDImportFile
When there’s more than one translator available:
kDTranslatorList ->
<- kDSetTranslator
kDImporting ->
<- kDResult
When there’s only one translator available:
kDImporting ->
<- kDResult
When the data is ready to be sent to the Newton:
kDSetStoreToDefault ->
<- kDResult
kDSetCurrentSoup ->
<- kDResult
kDAddEntry ->
<- kDAddedID
kDAddEntry ->
<- kDAddedID
kDSoupsChanged ->
Newton -> Desktop Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDImportFile 4 longs + string
'impt'
length
filename string
This command asks the desktop to import the file specified by the last path command and the filename string. The response to this can be either a list of translators (if there is more than one applicable translator) or an indication that importing is in progress. If the selected item is at the Desktop level, a frame {Name:“Business”, whichVol:-1} is sent. Otherwise, a string is sent.
kDSetTranslator 5 longs
'tran'
length # 4
translator index
This command specifies which translator the desktop should use to import the file. The translator index is the index into the translator list sent by the desktop in the kDTranslatorList command. The desktop should acknowledg this command with an indication that the import is proceeding.
Desktop-> Newton Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDTranslatorList 4 longs + length of array
'trnl'
length
array of strings
This command returns an array of translators that can be used with the specified file. The list can include DataViz translators and tab templates. The array should be in the order that the translators should be displayed in the list.
kDImporting 4 longs
'dimp'
length // 0
This command is sent to let the Newton know that an import operation is starting. The Newton will display an appropriate message after it gets this message.
kDSoupsChanged 4 longs + array
'schg'
length
array
This command returns information about what was imported into the Newton. Each array element specifies a soup and how many entries were added to it. There will typically be only one frame in the array. The frame will look like this:
[{soupName: "Notes", count: 7}, {soupName: "Names", count: 3}]
kDSetStoreToDefault 4 longs
'sdef'
length // # 0
This command can be used instead of kDSetCurrentStore. It sets the current store to the one the user has picked as the default store (internal or card).
Package loading
Package loading uses the file browsing interface described above. After the user taps the load package button, the following commands are used.
Newton -> Desktop Commands
kDLoadPackageFile 'lpfl'
Examples
After the load package button is tapped:
Desktop Newton
<- kDLoadPackageFile
kDLoadPackage ->
<- kDResult
Newton -> Desktop Detailed Commands
kDLoadPackageFile 4 longs + string
'impt'
length
filename string
This command asks the desktop to load the package specified by the last path command and the filename string. If the selected item is at the Desktop level, a frame {Name:“Business”, whichVol:-1} is sent. Otherwise, a string is sent.
Restore originated on Newton
Restore uses the file browsing interface described above. After the user taps the restore button, the following commands are used.
Newton -> Desktop Commands
kDRestoreFile 'rsfl'
kDGetRestoreOptions 'grop'
kDRestoreAll 'rall'
Desktop -> Newton or Newton -> Desktop
kDRestoreOptions 'ropt'
kDRestorePackage 'rpkg'
Examples
After the restore button is tapped:
Desktop Newton
<- kDRestoreFile
kDRes ->
<- kDGetRestoreOptions
kDRestoreOptions ->
<- kDRestoreOptions
kDSourceVersion ->
Selective restore proceeds as a normal restore would except when it wants to restore a package. In this case it does this:
kDRemovePackage->
kDResult
kDRestorePackage ->
<- kDResult
If the user picks a full restore it proceeds like this:
<- kDRestoreFile
kDRes ->
<- kDRestoreAll
kDSourceVersion ->
Newton -> Desktop Detailed Commands
kDRestoreFile 4 longs + filename
'impt'
length
filename
This command asks the desktop to restore the file specified by the last path command and the filename. If the selected item is at the Desktop level, a frame {Name:“Business”, whichVol:-1} is sent. Otherwise, a string is sent.
kDGetRestoreOptions 4 longs
'grop'
length
This command is sent to the desktop if the user wants to do a selective restore. The desktop should return a kDRestoreOptions command.
kDRestoreAll 5 longs
'rall'
length
merge
This command is sent to the desktop if the user elects to restore all information. Merge is 0 to not merge, 1 to merge.
Desktop -> Newton or Newton -> Desktop
kDRestoreOptions 4 longs + ref
'ropt'
length
restoreWhich
This command is sent to the newton to specify which applications and packages can be restored. It is sent in response to a kDRestoreFile command from the Newton. If the user elects to do a selective restore the Newton returns a similar command to the desktop indicating what should be restored.
restoreWhich # {storeType: kRestoreToNewton ,
packages: ["pkg1", ...],
applications: ["app1", ...]}
storeType indicates whether the data will be restored to a card (kRestoreToCard # 1) or the newton (kRestoreToNewton # 0).
kDRestorePackage 4 longs + ref
'rpkg'
length
package array
This command sends all the entries associated with a package to the newton in a single array. Packages are made up of at least 2 entries: one for the package info and one for each part in the package. All of these entries must be restored at the same time to restore a working package. A kDResult is returned after the package has been successfully restored.
Desktop Initiated Functions while connected
With the advent of the new protocol, the Newton and the desktop can be connected, but with no command specified. A command can be requested by the user on either the Newton or the Desktop. Commands requested by the newton user are discussed above. This section describes the commands sent from the Desktop to the Newton in response to a user request on the desktop.
Desktop -> Newton Commands
kDRequestToSync 'ssyn'
kDRequestToRestore 'rrst'
kDRequestToInstall 'rins'
Desktop -> Newton Detailed Commands
kDRequestToSync 4 longs
'ssyn'
length // # 0
This command is sent from the desktop when the desktop wants to start a sync operation, when both the newton and the desktop were waiting for the user to specify an operation.
kDRequestToRestore 4 longs
rrst
length // # 0
This command is sent from the desktop when the desktop wants to start a restore operation, when both the newton and the desktop were waiting for the user to specify an operation.
kDRequestToInstall 4 longs
rins
length // # 0
This command is sent from the desktop when the desktop wants to start a load package operation, when both the newton and the desktop were waiting for the user to specify an operation.
1.0 Newton ROM Support
Newton -> Desktop Commands
kDRequestToDock 'rtdk' // Ask PC to start docking process
kDNewtonName 'name' // The name of the newton
kDCurrentTime 'time' // The current time on the Newton
kDStoreNames 'stor' // data # array of store names & signatures
kDSoupNames 'soup' // data # array of soup names & signatures
kDSoupIDs 'sids' // data # array of ids for the soup
kDChangedIDs 'cids' // data # array of ids
kDResult 'dres' // data # command & result (error)
kDAddedID 'adid' // data # the id of the added entry
kDEntry 'entr' // data # entry being returned
kDPackageIDList 'pids' // data # list of package ids
kDPackage 'apkg' // data # package
kDIndexDescription 'indx' // data # index description array
kDInheritance 'dinh' // data # array of class, supperclass pairs
kDPatches 'patc' // no data
Desktop -> Newton
kDInitiateDocking 'dock' // data # session type
kDLastSyncTIme 'stme' // The time of the last sync
kDGetStoreNames 'gsto' // no data
kDGetSoupNames 'gets' // no data
kDSetCurrentStore 'ssto' // data # store frane
kDSetCurrentSoup 'ssou' // data # soup name
kDGetSoupIDs 'gids' // no data
kdGetChangedIDs 'gcid' // no date
kDDeleteEntries 'dele' // data # list of IDs
kDAddEntry 'adde' // data # flattened entry
kDReturnEntry 'rete' // data # ID to return
kDReturnChangedEntry 'rcen' // data # ID to return
kDEmptySoup 'esou' // no data
kDDeleteSoup 'dsou' // no data
kDLoadPackage 'lpkg' // data # package
kDGetPackageIDs 'gpid' // no data
kDBackupPackages 'bpkg' // no data
kDDisconnect 'disc' // no data
kDDeleteAllPackages 'dpkg' // no data
kDGetIndexDescription 'gind' // no data
kDCreateSoup 'csop' // data # name + index description
kDGetInheritance 'ginh' // no data
kDSetTimeout 'stim' // data # # of seconds
kDGetPatches 'gpat' // no data
kDDeletePkgDir 'dpkd' // no data
kDGetSoupInfo 'gsin' // no data
Desktop -> Newton or Newton -> Desktop
kDChangedEntry 'cent' // data # entry being returned
kDTest 'test' // variable length data
kDHello 'helo' // no data
kDSoupInfo 'sinf' // data # soup info frame
Examples
Every session starts like this:
Desktop Newton
<- kDRequestToDock
kDInitiateDocking ->
<- kDNewtonName
kDSetTimeout ->
<- kDResult
No matter what the intent of the desktop or the Newton, these commands must always start a session (the desktop can substitute a kDResult for the kDSetTimeout if it doesn’t want to set the timeout).
A typical synchronize session might continue like this:
Desktop Newton
kDGetStoreNames ->
<- kDStoreNames
kDLastSyncTime -> // This ones fake just to get the newton time
<- kDCurrentTime
kDSetCurrentStore ->
<- kDResult
kDLastSyncTIme ->
<- kDCurrentTime
kDGetPatches ->
<- kDPatches
kDGetPackageIDs ->
<- kDPackageIDList
kDBackupPackages ->
<- kDPackage
kDBackupPackages ->
<- kDPackage
kDBackupPackages ->
<- kDResult
kDGetSoupNames ->
<- kDSoupNames
kDGetInheritance ->
<- kDInheritance
kDSetCurrentSoup ->
<- kDResult
kDGetSoupInfo ->
<- kDSoupInfo
kDGetSoupIDs ->
<- kDSoupIDs
kdGetChangedIDs ->
<- kDChangedIDs
kDDeleteEntries ->
<- kDResult
kDAddEntry ->
<- kDAddedID
kDReturnEntry ->
<- kDEntry
kDDisconnect ->
A restore session would look like this:
Desktop Newton
kDGetStoreNames ->
<- kDStoreNames
kDSetCurrentStore ->
<- kDResult
kDDeleteAllPackages ->
<- kDResult
kDGetSoupNames ->
<- kDSoupNames
kDSetCurrentSoup ->
<- kDResult
kDEmptySoup ->
<- kDResult
kDAddEntry ->
<- kDResult
kDDeletePkgDir ->
<- kDResult
kDLoadPackage ->
<- kDResult
kDDisconnect ->
A load package session would look like this:
Desktop Newton
kDLoadPackage ->
<- kDResult
kDDisconnect ->
Newton -> Desktop Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDRequestToDock: 4 longs
'rtdk'
length
protocol version
This command is sent to a docker that the junior wishes to connect with (on the network, serial, etc.). The Newt expects a kDInitiateDocking command in response. The protocol version is the version of the messaging protocol that’s being used
kDSetTimeout
'stim'
length
timeout in seconds
This command sets the timeout for the connection (the time the Newton will wait to receive data for it disconnects). This time is usually set to 30 seconds.
kDNewtonName 4 longs + version info + name
'name'
length
version info
name
This command is sent in response to a correct kDInitiateDocking command from the docker. The Newton’s name is used to locate the proper synchronize file. The version info includes things like machine type (e.g. J1), ROM version, etc.
kDStoreNames: 4 longs + names array
'stor'
length
array of frames
This command is sent in response to a kDGetStoreNames command. It returns information about all the stores on the Newton. Each array slot contains the following information about a store:
{Name: "",
signature: 1234,
totalsize: 1234,
usedsize: 1234,
kind: "",
info: {store info frame},
readOnly: true,
defaultStore: true, // only for the defaultstore
storePassword: password // only if a store password has been set
}
kDSoupNames: 5 longs + names array
'soup'
length
[names] // array of strings
[signatures/ // array of corresponding soup signatures
This command is sent in response to a kDGetSoupNames command. It returns the names and signatures of all the soups in the current store.
kDIndexDescription 4 longs + index description
'didx'
length
indexes
This command specifies the indexes that should be created for the current soup.
kDSoupIDs: 5 longs + array length
'sids'
length
count // count of elements in the ids array
[ids] // array of ids for the soup
This command is sent in response to a kDGetSoupIDs command. It returns all the IDs from the current soup.
kDChangedIDs: 5 longs + array length
'cids'
length
count // count of elements in the ids array
[ids] // array of ids for the soup
This command is sent in response to a kDGetChangedIDs command. It returns all the ids with mod time > the last sync time. If the last sync time is 0, no changed entries are returned (this would happen on the first sync).
kDResult: 5 longs
'dres'
length // # 4
error code // A long
This command is sent in response to any of the commands from the PC that don’t request data. It lets the PC know that things are still proceeding OK.
kDAddedID: 5 longs
'adid'
length // # 4
ID // a long
This command is sent in response to a kDAddEntry command from the PC. It returns the ID that the entry was given when it was added to the current soup.
kDEntry: 4 longs + data
'entr'
length // Length of flattened entry data
entry // binary data
This command is sent in response to a KDReturnEntry command. The entry in the current soup specified by the ID in the KDReturnEntry command is returned.
kDPackageIDList: 5 longs + data
'pids'
length // Length of package id list
count // the number of packages
package info
This command sends a list of package frames to the desktop. For each package the information sent is this:
ULong packageSize;
ULong packageId;
ULong packageVersion;
ULong format;
ULong deviceKind;
ULong deviceNumber;
ULong deviceId;
ULong modifyDate;
ULong isCopyProtected;
ULong length;
Character name; // length bytes of unicode string
Note that this is not sent as an array! It’s sent as binary data. Note that this finds packages only in the current store.
kDPackage: 5 longs + data
'apkg'
length // Length of package
package ID
entry // package data
This command sends a package to the pc. It’s issued repeatedly in response to a kDBackupPackages message.
Desktop-> Newton Detailed Commands
All commands begin with ’newt’, ‘dock’ so that’s not shown below.
kDInitiateDocking: 5 longs
'dock'
length // 4
session type
This command is sent to the newt in response to a kDRequestToDock command. Session type can be one of {none, settingUp, synchronize, restore, loadPackage, testComm, loadPatch, updatingStores}.
kDGetSoupNames: 3 longs
'gets' // no data
length // # 0
This command is sent when a list of soup names is needed. It expects to receive a kDSoupNames command in response.
kDSetCurrentStore 4 longs + frame length
'ssto'
length
store frame
This command sets the current store on the Newton. A store frame is sent to uniquely identify the store to be set:
{
name: "foo",
kind: "bar",
signature: 1234,
info: {<info frame>} // This one is optional
}
kDSetCurrentSoup 4 longs + soup name
'ssou'
length
soup name // C string
This command sets the current soup. Most of the other commands pertain to this soup so this command must preceed any command that uses the current soup. If the soup doesn’t exist a kDSoupNotFound error is returned but the connection is left alive so the desktop can create the soup if necessary. Soup names must be < 25 characters.
kDGetIndexDescription 4 longs
'gidx'
length // # 0
This command requests the definition of the indexes that should be created for the current soup.
kDGetSoupIDs 3 longs
'gids'
length // # 0
This command is sent to request a list of entry IDs for the current soup. It expects to receive a kDSoupIDs command in response.
kDGetChangedIDs 3 longs
'gids'
length // # 0
This command is sent to request a list of changed IDs for the current soup. It expects to receive a kDChangedIDs command in response.
kDDeleteEntries: 5 longs + array length
'dele'
length
count of ids in the array
[ids] // IDs to delete
This command is sent to delete one or more entries from the current soup.
kDAddEntry: 4 longs + entry data
'adde'
length // length of data
data // entry ref
This command is sent when the PC wants to add an entry to the current soup.
kDReturnEntry: 4 longs
'rete'
length // # 4
id // ID of the entry to return
This command is sent when the PC wants to retrieve an entry from the current soup.
kDReturnChangedEntry: 4 longs
'rcen'
length // # 4
id // ID of the entry to return
This command is sent when the PC wants to retrieve a changed entry from the current soup.
kDEmptySoup: 4 longs + soup name
'dsou'
length
soup name // C string
This command is used by restore to remove all entries from a soup before the soup data is restored.
kDDeleteSoup: 4 longs + soup name
'dsou'
length
soup name // C string
This command is used by restore to delete a soup if it exists on the Newton but not on the PC.
kDLoadPackage: 4 longs + package
'lpkg'
length
package data // binary data
This command will load a package into the Newton’s RAM. The package data should be padded to an even multiple of 4 by adding zero bytes to the end of the package data.
kDGetPackageIDs 4 longs
'gpid'
length // # 0
This command is sent to request a list of package ids. This list is used to remove any packages from the PC that have been deleted on the Newt.
kDBackupPackages 4 longs
'bpkg'
length // # 0
This command is sent to backup any packages that are installed on the Newton. It expects a kDPackage command or a kDResponse with an error of 0 (to indicate that there are no more packages) in response.
kDDisconnect: 3 longs
'disc'
length // # 0
This command is sent to the Newton when the docking operation is complete.
Desktop -> Newton or Newton -> Desktop Detailed Commands
kDChangedEntry: 4 longs + data
'cent'
length // Length of flattened entry data
entry // binary data
This command is sent by the newton in response to a KDReturnChangedEntry command from the desktop. It can also be sent by the desktop.
kDHello: 4 longs
'helo'
length // 0
This command is sent during long operations to let the newton or desktop know that the connection hasn’t been dropped.
kDSoupInfo 4 longs + soup info frame
'sinf'
length // 0
soup info frame
This command is used to send a soup info frame. When received the info for the current soup is set to the specified frame.
Compatibility
The protocol described above for 2.0 is a superset of the 1.0 protocol. However, the protocol version has been incremented so old versions of Newton Connection will no longer work with this version. The reason for this is that, although the protocol itself is upwardly compatable, the data structures in other parts of the 2.0 newton have changed to such a degree that old versions of Newton Connection will no longer work.
NTK
"pkgX" DeletePackage
"code" HandleCodeBlock which takes an NSOF function frame and interprets it.
"rslt" Returns some result back to NTK
"text" Sends some text header to NTK
"eext" Enter Breakloop
"bext" Exit Breakloop
"eref" Sends Exception Data (cahr *msg, RefArg data)
"estr" Sends Exception Data (char *msg, char *data)
"eerr" Sends Exception Data (char *msg, long ErrNo)
"fstk" Sends a stackframe to NTK
"okln" Sent by NTK to ACK connection, if not Newton respods with Error -28016
"cnnt" Requests an NTK connection from the desktop
"term" Requests disconnect (?) (Not quite sure about yet)
"pkg " LoadPackage
"stou" Set timeout
"dpkg" ?? Probably request for Package Download
"fobj" Sends any arbitrary Newton Object as NSOF to NTK