Data Stream Interface
Encyclopedia
The Data Stream Interface (DSI) is a session layer used to carry Apple Filing Protocol
traffic over Transmission Control Protocol
.
and Open Transport
in System 7
in the 1990s, they needed their file sharing protocol (AFP) to run on both TCP and AppleTalk
. They introduced AppleTalk Session Protocol (ASP) and DSI for TCP coincidentally with AFP 2.x.
DSI is implemented directly into AFP clients such as in Mac OS and afpfs-ng.
The fields are:
The DSITickle and DSICloseSession commands do not trigger a reply.
Session closure can be initiated by either side by sending DSICloseSession. The sender does not need to wait for a reply and should immediately close the session after sending the message.
Maintaining the connection is done by tickling. DSI provides a mechanism for ensuring that client and server know that the other is still active. Every 30 seconds of inactivity, the server sends a tickle request to the client. Similarly, the client also sends its own tickle. (This is NOT a response packet.) Either the client or server can terminate the DSI session if they fail to hear from the other for 120 seconds. The client may also disconnect if a request is in flight and neither a response nor tickle is received within 60 seconds (in Mac OS X v.10.2 and later).
The data elements are organized in the packet with a catalog of indices pointing to structured data.
The request to a DSIGetStatus request will cause the server to respond with the following information:
DSIGetStatus reply format is identical to AFP's FPGetSrvrInfo and is used for ASPGetStatus..
The most succinct guide is the "AFP over TCP" chapter of Apple Filing Protocol Programming Guide.
A significant source of information in understanding DSI can be found by analyzing communication between AFP clients and servers using a packet sniffer.
Apple Filing Protocol
The Apple Filing Protocol is a network protocol that offers file services for Mac OS X and original Mac OS. In Mac OS X, AFP is one of several file services supported including Server Message Block , Network File System , File Transfer Protocol , and WebDAV...
traffic over Transmission Control Protocol
Transmission Control Protocol
The Transmission Control Protocol is one of the core protocols of the Internet Protocol Suite. TCP is one of the two original components of the suite, complementing the Internet Protocol , and therefore the entire suite is commonly referred to as TCP/IP...
.
Overview
When Apple introduced TCP with MacTCPMacTCP
MacTCP was the standard TCP/IP implementation for the Macintosh operating system through version 7.5.1. It was the first application-independent implementation of a TCP stack for a non-Unix platform and predates Winsock by over 5 years...
and Open Transport
Open Transport
Open Transport was the name given by Apple Inc. to their implementation of the Unix-originated System V STREAMS. Based on code licensed from Mentat's Portable Streams product, Open Transport was built to provide the Mac OS with a modern TCP/IP implementation, replacing MacTCP...
in System 7
System 7
System 7 is the name of a Macintosh operating system introduced in 1991.System 7 may also refer to:* System 7 , a British dance/ambient band* System 7 , 1991 album* IBM System/7, a 1970s computer system...
in the 1990s, they needed their file sharing protocol (AFP) to run on both TCP and AppleTalk
AppleTalk
AppleTalk is a proprietary suite of protocols developed by Apple Inc. for networking computers. It was included in the original Macintosh released in 1984, but is now unsupported as of the release of Mac OS X v10.6 in 2009 in favor of TCP/IP networking...
. They introduced AppleTalk Session Protocol (ASP) and DSI for TCP coincidentally with AFP 2.x.
DSI is implemented directly into AFP clients such as in Mac OS and afpfs-ng.
Protocol
DSI is spoken between a client and an AFP server. All DSI communication contains the following DSI header:Packet structure
| Bit offset | Bits 0–7 | 8-15 | 15-23 | 24-31 | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Flags | Command | Request ID | |||||||||||||||||||||||||||||
| 32 | Error code/ enclosed data offset | |||||||||||||||||||||||||||||||
| 64 | Total data length | |||||||||||||||||||||||||||||||
| 96 | Reserved | |||||||||||||||||||||||||||||||
| 128 | Payload | |||||||||||||||||||||||||||||||
The fields are:
- Flags: whether the packet is a request (0x00) or a reply (0x01)
- Command: one of 7 possible commands (see below)
- Request ID: a sequential identifier set on the request and copied in the reply
- Error code/ enclosed data offset:
- For requests, this is left as 0, except when using the DSIWrite command.
- For replies, this is an error code.
- Total data length: the entire length of data after the DSI header
- Reserved: for future expansion
- Payload: this is where limited DSI data or more commonly AFP header is placed
Commands
There are seven possible commands:| Name | Code | Direction | Description |
|---|---|---|---|
| DSICloseSession | 1 | Both | Closes an established session |
| DSICommand | 2 | From client | Attached payload contains an AFP command |
| DSIGetStatus | 3 | From client | Get information about the server |
| DSIOpenSession | 4 | From client | Establish a new session |
| DSITickle | 5 | Both | Ensure the connection is active |
| DSIWrite | 6 | From client | Write data to the server |
| DSIAttention | 8 | From server | Get the attention of the client |
Requests and replies
Upon receiving most DSI requests, the client or server sends a reply message. This reply contains:- the flags field set to 0x01 (reply)
- the command field set to the same value as the request's command field
- the same request ID sent in the request (used for the client to find the request being acknowledged)
- totalDataLength set to the payload length (if applicable).
- where applicable, the data payload itself following the DSI header. (See the individual command for details.)
The DSITickle and DSICloseSession commands do not trigger a reply.
Session creation, maintenance and teardown
A session is set up by the client sending a DSIOpenSession, which will include the size of the receive buffer the client has for packets (called the request quantum, typically 1024 bytes). The server acknowledges the request and returns the size of its data receive buffer (typically 256k on Mac OS X Leopard).Session closure can be initiated by either side by sending DSICloseSession. The sender does not need to wait for a reply and should immediately close the session after sending the message.
Maintaining the connection is done by tickling. DSI provides a mechanism for ensuring that client and server know that the other is still active. Every 30 seconds of inactivity, the server sends a tickle request to the client. Similarly, the client also sends its own tickle. (This is NOT a response packet.) Either the client or server can terminate the DSI session if they fail to hear from the other for 120 seconds. The client may also disconnect if a request is in flight and neither a response nor tickle is received within 60 seconds (in Mac OS X v.10.2 and later).
Getting server information with GetStatus
This DSI command encapsulates an FPGetSrvrInfo packet. It is used by a client to get information from a server it isn't logged into.The data elements are organized in the packet with a catalog of indices pointing to structured data.
The request to a DSIGetStatus request will cause the server to respond with the following information:
- flags for basic server characteristics
- server name (7-bit ASCII and UTF-8)
- signature: used to uniquely identify the server for other AFP transactions
- server type: typically "Macintosh" or "Netatalk"
- a list of strings describing AFP versions spoken (e.g. "AFP3.2")
- UAM list: a list of strings describing User Authentication Methods (e.g. "DHX2")
- a 64x64 pixel icon
- directory server list
DSIGetStatus reply format is identical to AFP's FPGetSrvrInfo and is used for ASPGetStatus..
Further research
DSI is never documented separately, and is sufficiently simple and static that older references are suitable for modern implementations. The concepts of DSI are identical to AppleTalk Session Protocol (ASP), and the overview in Inside AppleTalk, Second Edition can be helpful.The most succinct guide is the "AFP over TCP" chapter of Apple Filing Protocol Programming Guide.
A significant source of information in understanding DSI can be found by analyzing communication between AFP clients and servers using a packet sniffer.