[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
AS#2 - Internet Draft Proposal - 2/3
QUIT <CRLF>
In the HELO command the host sending the command is merely recording the
start of a logical session. It is important that the client note the
response to the HELO command, since the result code indicates whether
the server is capable of receiving new incoming documents during the
session.
Example of Connection Opening
S: 220 BDG.Actracorp ECTP Service Ready
C: HELO
S: 200 BDG.Actracorp Ready - SEND allowed
Example of Connection Closing
C: QUIT
S: 205 BDG.Actracorp Service closing connection - Goodbye!
3.2. SEND
After circuit establishment, there are three steps in sending a document
from client to server. The transaction is started with a SEND command
which gives the sender identification. An RCPT command follows, giving
the receiver information.
Then a DATA command signals that the data follows, up to the end-of-data
marker. The data can be a MIME or S/MIME-encapsulated document. Note
that in a well-known environment between client and server, the data can
be a transaction understood by the listening application; an extended
response defined between the partners could return the result of the
transaction. Furthermore, a well known environment could define that the
SEND and RCPT define the connection or envelope, and that multiple
DATA/Responses are possible. In other words, as long as the same sender
and receiver are in effect, multiple transactions can flow between the
applications on the client and server, using the DATA command as the
transaction submitter.
Independent of use, the first step in the procedure is the SEND command.
The < Trading Partner ID > contains the source user identification - the
ID in the client's domain.
SEND <SP> FROM:<Trading Partner ID> <CRLF>
This command tells the server that a new document transaction is
starting and to reset all its state tables and buffers, including any
recipient or document data. It gives the reverse-path which can be used
to report errors. The reverse-path is also important since it is the
true sender identification within the sender's domain, when more than
one possible sender exists. If the document to send was an EDI
interchange, then the reverse-path is the trading partner identifier
within the sender domain.
The second step in the procedure is the RCPT command.
RCPT <SP> TO:< Trading Partner ID > <CRLF>
This command tells the server the recipient's ID within the server's
domain. In the EDI model, this would be the trading partner identifier
within the target domain. If accepted, the server returns a 250 OK
reply, and stores the Trading Partner ID. If the recipient is unknown
the server returns a 453 Failure reply. Since the ECTP model provides
no forwarding and no distribution lists (a message or document goes from
source to destination only, where destination is logically at the server
domain), there can be only one RCPT, as compared with SMTP where this
second step of the procedure can be repeated any number of times.
The third step in the procedure is the DATA command.
DATA [senders_control_number]<CRLF>
If accepted, the server returns a 354 Intermediate reply and considers
all succeeding lines to be the message text. When the end of text is
received and stored the server sends a 250 OK reply, along with the
control number (tracking number) assigned to the data. This can be
either the sender_control_number if one was specified with the DATA, or
one assigned by the server on successful receipt of the data. MIME
encapsulation is used for all ECTP-transmitted data, supporting all
MIME-types. The MIME headers and data would be sent at this time.
Like SMTP on which SEND is based, ECTP indicates the end of the
encapsulated data by sending a line containing only a period. The end of
data indicator also confirms the document/message transaction, and tells
the server to now process the stored routing, metadata and data. If
accepted, the receiver-ECTP returns a 251 control_number Received OK
reply. The DATA command should fail only if the transaction was
incomplete (for example, no recipient specified), or if resources are
not available. The 251 response specifies a unique tracking number
assigned by the server to the data just received. While the client-
assigned tracking number from the DATA command, if specified, is
associated with the data, it can not be trusted to be unique from the
server perspective. The server-generated tracking number is what will be
enumerated on LIST commands, and is what the GETDOCS command can specify
for retrieval.
In case of an abnormal disconnect, there is no restart facility provided
in the protocol. Until the time that the submission of the data object
is confirmed by the server, the client is obliged to consider the
transfer of ownership incomplete. The client would reinstate the
connection and recommence the SEND operation from the beginning. Once
the server tracking number is returned to the client, the atomic
operation may be considered complete.
The command sequence must proceed exactly as specified. The LIST command
could be used by the client to retrieve potential trading partner
recipients at the server domain in conjunction with the SEND sequence.
This would be performed prior to the SEND sequence, since both sequences
must remain intact.
A typical SEND sequence might look as follows. The RCPT to an incorrect
trading partner was introduced only to show that an error in one part of
the transaction interchange does not preclude recovery by an intelligent
client agent. Further, it might well have been a person at an
interactive program that specified an incorrect trading partner id the
first time. The second RCPT error is shown to reinforce the fact that
this is point to point, and is not intended to support one-to-many
forwarding.
C: SEND FROM kschwab_invoicing<CRLF>
S: 250 OK
C: RCPT TO jp124385<CRLF>
S: 451 Trading Partner ID Unknown
C: RCPT TO jp124384<CRLF>
S: 250 OK
C: RCPT TO jp124322<CRLF>
S: 455 Recipient Already Specified
C: DATA PO12345
S: 354 Ready to Receive
C: Client sends data, raw, MIME or S/MIME encapsulated
C: .<CRLF>
S: 251 189999234 Received OK
3.3. Query and Enumeration
ECTP provides the LIST command to perform query functions on Documents.
Client/Server pairs are free to define new object types known to both,
along with any criteria that makes sense to the object type. The syntax
and semantics for object type Documents, however, must be adhered to as
specified in this document.
That is not to say that the usage of the enumeration is not under
control of the client implementers. That is, the enumeration can be used
for client reporting on document status or as a precursor to retrieval
of a specific document. To serve the needs of document retrieval, there
is a special command to encapsulate enumeration and retrieval of as yet
unretrieved documents - see GETDOCS and NEXT. Further, GETDOCS is the
method of retrieving explicitly specified document ids.
LIST is an atomic command; there is no connection with the use of the
data returned, nor any connection with a subsequent or previous command.
The format of the LIST command will be fully discussed in section 5. For
now, a valid format for document lists is as follows:
LIST DOCUMENTS
This command enumerates the available documents destined for the
client's location. It is the most general form of the command, and would
result in those documents not already retrieved by the client. So the
scenario would look like this:
C: LIST DOCUMENTS
S: 215 Listing Follows
S: 186523345 XX:12345 ZZ:Kent Unretrieved 19960915 PO12345
S: 186523666 YY:23456 ZZ:Kent Unretrieved 19960916 IN23345
S: 186523787 XX:12345 ZZ:Kent Unretrieved 19960916 PO23456
S: .
Retrieval criteria can be added to retrieve documents already retrieved,
by date, by recipient or sending partner id. The maximum number of
matches to permit for a single retrieval is also a possible argument to
the LIST command; the NEXT would be required to retrieve subsequent
matches meeting the initial criteria.
3.4. Document Retrieval
In most cases, the reason for document enumeration using the LIST
command is to cause a transfer of a specific document or documents which
meet retrieval criteria. But as stated, there is no connection between
the LIST command and any subsequent command by the client. It is the
client application's responsibility to examine the results of the
enumeration, and to request retrieval by key, of those documents
desired. To make the common task of retrieving all unretrieved documents
easier for the client, a special command is provided. The retrieval, by
document key, is performed by the GETDOCS command. The retrieval of the
next unretrieved document, without need for enumeration, is performed by
the NEXT command.
As in the SEND command, the data is encapsulated using MIME or S/MIME.
The command flow is as follows for DOCUMENT-specific retrieval. When the
document key is specified, the server confirms its availability, and
waits for the DATA command, indicating that the client is ready to
receive.
C: LIST DOCUMENTS STATUS: Retrieved FROM: "XX:12345"
S: 215 Listing Follows
S: 186523345 XX:12345 ZZ:Kent Retrieved 19960917 PO12345
S: 186523787 XX:12345 ZZ:Kent Retrieved 19960917 PO23456
S: . <CR><LF>
C: GETDOCS DOCID = 186523345
S: 240 Ready to Transfer
C: DATA
S: server sends the data, encapsulated in MIME
S: . <CR><LF>
C: GETDOCS DOCID =186523787
S: 240 Ready to Transfer
C: DATA
S: server sends the data, encapsulated in MIME
S: . <CR><LF>
C: GETDOCS DOCID =188889787
S: 430 no such document found
The commands GETDOCS, with no specific document id retrieval criteria,
and NEXT can be considered a shortcut, encapsulating a LIST command,
followed by document retrieval by key. It saves the client from having
to store the results of the query, and enables easier sequential
retrieval of documents. The default for GETDOCS is for all unretrieved
documents. Criteria for retrieval is only set at the GETDOCS time; NEXT
is used to retrieve the next document which meets the specified
criteria. The optional criteria, when specified, are used to restrict
which document set is to be processed - typically by trading partner
identifier, date, status, or specific document id.
A typical scenario to retrieve all unretrieved documents would look like
this:
C: GETDOCS
S: 210 Document Set Prepared
C: NEXT
S: 240 Ready to Transfer
C: DATA
S: server sends the data, encapsulated in MIME
S: . <CR><LF>
C: NEXT
S: 240 Ready to Transfer
C: DATA
S: server sends the data, encapsulated in MIME
S: . <CR><LF>
C: NEXT
S: 440 No More Documents
IV. The ECTP Specification
4.1. Overview
The ECTP server specified by this document uses a stream connection
(such as TCP) and SMTP-like commands and responses. It is intended to
use a secure socket interface, such as SSL, and authentication
techniques, such as certificate exchange, outside the domain of this
application protocol.
This server is an interface between programs implementing the client-
server protocol on both sides; it does not perform any user interaction
or presentation-level functions. Shared with NNTP, these "user-friendly"
functions are better left to the client programs, which have a better
understanding of the environment in which they are operating.
When used via Internet TCP, the contact port assigned for this service
is (To Be Determined).
4.2. Character Set
Commands and replies are composed of characters from the ASCII character
set. When the transport service provides an 8-bit byte (octet)
transmission channel, each 7-bit character is transmitted right
justified in an octet with the high order bit cleared to zero.
4.3. Commands
Commands consist of a command word, which in some cases may be followed
by a parameter. Commands with parameters must separate the parameters
from each other and from the command by one or more space or tab
characters. Command lines must be complete with all required parameters
and may not contain more than one command.
Commands and command parameters are not case sensitive. That is, a
command or parameter word may be upper case, lower case, or any mixture
of upper and lower case.
Each command line must be terminated by a CR-LF (Carriage Return - Line
Feed) pair.
Command lines shall not exceed 512 characters in length, counting all
characters including spaces, separators, punctuation, and the trailing
CR-LF (thus there are 510 characters maximum allowed for the command and
its parameters). There is no provision for continuation command lines.
4.4. Responses
Like NNTP, responses are of several kinds.
4.4.1. Data Responses
Taking the place of the NNTP Text response, the Data Response is sent
only after a numeric status response line has been sent that indicates
that data will follow. Data is sent as a series of successive lines of
textual matter, each terminated with CR-LF pair.
A single line containing only a period (.) is sent to indicate the end
of the data (i.e., the server will send a CR-LF pair at the end of the
last line of text, a period, and another CR-LF pair).
If the data contained a period as the first character of the text line
in the original, that first period is doubled. Therefore, the client
must examine the first character of each line received, and for those
beginning with a period, determine either that this is the end of the
text or whether to collapse the doubled period to a single one.
While in NNTP the intention is that text messages will usually be
displayed on the user's terminal, command/status responses will be
interpreted by the client program before any possible display is done.
In ECTP the contents of Data Responses may or may not be presented to an
end user, and will always be interpreted by a process, even when
displayed. Data responses are used to express the results of a
successful query or enumeration request. The use of the results is
totally at the discretion of the user of the protocol implementation.
The use of the term Data Responses instead of NNTP's Text Responses is
intended to broaden the potential use of Data Responses.
4.4.2. Status Responses
As in SMTP, a reply consists of a three digit number (transmitted as
three alphanumeric characters) followed by some text. The number is
intended for use by automata to determine what state to enter next; the
text is meant for the human user. It is intended that the three digits
contain enough encoded information that the client does not need to
examine the text and may either discard it or pass it on to the user, as
appropriate. In particular, the text may be receiver-dependent and
context dependent, so there are likely to be varying texts for each
reply code.
Formally, a reply is defined to be the sequence: a three-digit code,
<SP>, one line of text, and <CRLF>.
Status responses are reports from the server indicating to the client
the results of the last command received. Status response lines begin
with a 3-digit numeric code that is sufficient to distinguish all
responses. Some of these may herald the subsequent transmission of
data, in the form of Data Responses.
The first digit of the response broadly indicates the success, failure,
or progress of the previous command. This definition is shared between
SMTP and NNTP, and therefore ECTP.
1xx - Informative message
2xx - Command OK
3xx - Command OK so far, send the rest of it.
4xx - Command was correct, but couldn't be performed for some
reason.
5xx - Command unimplemented, or incorrect, or a serious program
error occurred.
The next digit in the code indicates the function response category.
This, by definition, must be ECTP-unique; there is no overlap between
SMTP and NNTP categories. The NNTP categories have been preserved to
the extent possible since there was higher correlation between NNTP
services and the additional categories in ECTP:
x0x - Connection (transmission channel)
x1x - Group or Criteria selection
x2x - Document selection
x3x - Enumeration or Listing functions
x4x - Retrieval functions (Server->Client transmission)
x5x - Send (Client->Server transmission)
x6x - Information (status or help)
x8x - Nonstandard (private implementation) extensions
x9x - Debugging output
The third digit gives a finer gradation of meaning in each category
specified by the second digit. Server implementations should not invent
new codes for slightly different situations from the ones described
here, but rather adapt codes already defined.
The exact response codes that should be expected from each command are
detailed in the description of that command. In addition, section 4.4.3
lists a general set of response codes that may be received at any time.
Certain status responses contain parameters such as numbers and names.
The number and type of such parameters is fixed for each response code
to simplify interpretation of the response.
Parameters are separated from the numeric response code and from each
other by a single space. All numeric parameters are decimal and may have
leading zeros. All string parameters begin after the separating space,
and end before the following separating space or the CR-LF pair at the
end of the line. (String parameters may not, therefore, contain spaces.)
------------------------------------------------------
| Rik Drummond - The Drummond Group |
| 5008 Brentwood Ct., Ft. Worth, TX 76132 USA |
| Voice: 817 294 7339 Fax: 817 294 7950 |
------------------------------------------------------