MailTransport5.cr
Copyright Ó 1987, 1988, 1991 by Xerox Corporation. All rights reserved.
MChen, 08-Apr-87 09:56:01 PDT
Bill Jackson (bj) November 7, 1988 1:50:30 pm PST
Doug Terry, November 9, 1988 4:12:29 pm PST
The complete declaration of the MailTransport protocol is given below.
MailTransport: PROGRAM 17 VERSION 5 = BEGIN
DEPENDS UPON
Authentication (14) VERSION 2,
BulkData (0) VERSION 1,
CHName (2) VERSION 0,
CHOps (2) VERSION 3;
Types and Constants
Credentials: TYPE = Authentication.Credentials;
ContentsType: TYPE = LONG CARDINAL;
Verifier: TYPE = Authentication.Verifier;
Session: TYPE = RECORD [ token: SessionToken, verifier: Verifier ];
SessionToken: TYPE = ARRAY 2 OF UNSPECIFIED;
EnvelopeItemType: TYPE = LONG CARDINAL;
EnvelopeItem: TYPE = RECORD [ type: EnvelopeItemType, value: Opaque ];
Opaque: TYPE = SEQUENCE OF UNSPECIFIED;
Envelope: TYPE = SEQUENCE 100 OF EnvelopeItem;
there can be up to 100 envelope items in an envelope.
InvalidName: TYPE = RECORD [ id: CARDINAL, invalidReason: InvalidReason ];
InvalidNameList: TYPE = SEQUENCE OF InvalidName;
InvalidReason: TYPE = {
noSuchRecipient(0), -- recipient does not exist
noMailboxForRecipient(1),
illegalName(2), -- specified name is not a valid RName
noDLsAllowed(3), -- occurs only when allowDLRecipients=FALSE
reportNotAllowed(4) -- reports are not allowed on DLs
};
Name: TYPE = CHName.Name;
ReportType: TYPE = { none(0), nonDeliveryOnly(1), all(2) };
Widened the field out (WIrish) since we DO see other values from servers/clients (uninitialized values is my guess).
Sirocco can't seem to handle LAST[CARDINAL] or LAST[CARD16] so I had to use 65535.
ReportType: TYPE = { none(0), nonDeliveryOnly(1), all(2), unknown(65535)};
Recipient: TYPE = RECORD [
name: RName,
recipientID: CARDINAL,
report: ReportType
];
RecipientList: TYPE = SEQUENCE OF Recipient;
RNameKind: TYPE = { xns(0), gateway(1) };
RName: TYPE = CHOICE RNameKind OF {
xns => Name,
gateway => GatewayRecord
};
OrgUnits: TYPE = SEQUENCE 20 OF STRING;
BrokenName: TYPE = RECORD [
given: STRING,
initials: STRING,
family: STRING,
generation: STRING
];
PerChoiceKind: TYPE = { whole(0), broken(1) };
PerChoice: TYPE = CHOICE PerChoiceKind OF {
whole => STRING,
broken => BrokenName
};
GatewaySpecInfo: TYPE = SEQUENCE 10 OF Attribute;
there can be up to 10 pieces of gatewaySpecificInformation in a name
GatewayRecord: TYPE = RECORD [
country: STRING,
adminDomain: STRING,
privateDomain: STRING,
organization: STRING,
organizationalUnits: OrgUnits,
there can be up to 20 organizationalUnits in a name.
personal: PerChoice,
gatewaySpecificInformation: GatewaySpecInfo
];
Attribute: TYPE = RECORD [
type: STRING,
value: STRING
];
The following Attributes are defined to allow the use of non-standard X.400 name forms:
type: value:
'X121Address' string of digits (max 15 bytes)
'TerminalID' string of characters, (ASCII, max 24 bytes)
'UAIdentifier' string of digits (max 32 bytes)
'FreeFormName' string of characters (Xerox Character Code Standard, max 64 bytes)
'TelephoneNumber' string of digits (max 32 bytes)
Willingness[i] gives the service's ability to accept a message of size 8i to size 8(i +1). The last element in the sequence gives willingness from 8(index of last element) out to infinity.
WillingnessMetric: TYPE = CARDINAL; -- Ranges from 1 (unwilling) to 10 (very willing);
Willingness: TYPE = SEQUENCE 12 OF WillingnessMetric;
this sequence will typically contain fewer than 12 elements.
BodyPartType: TYPE = LONG CARDINAL; -- types of constituent message pieces
BPSeq: TYPE = SEQUENCE 500 OF BodyPartType;
Information used by the Mail Service to construct the message envelope.
PostingData: TYPE = RECORD [
recipients: RecipientList,
contentsType: ContentsType,
contentsSize: LONG CARDINAL,
bodyPartTypesSequence: BPSeq
];
OptionalEnvItemSeq: TYPE = SEQUENCE OF EnvelopeItem;
MessageID: TYPE = ARRAY 5 OF UNSPECIFIED;
Remote Procedures
Posting Slot Procedures
credentials: Credentials, verifier: Verifier ??? gone
ServerPoll: PROCEDURE [ ]
RETURNS [willingness: Willingness, address: CHOps.NetworkAddressList, serverName: Name] = 0;
BeginPost: PROCEDURE [envelopeData: PostingData, postIfInvalidNames: BOOLEAN, allowDLRecipients: BOOLEAN, optionalEnvelopeData: OptionalEnvItemSeq, credentials: Credentials, verifier: Verifier]
RETURNS [session: Session, invalidNames: InvalidNameList]
REPORTS [AuthenticationError, InvalidRecipients, OtherError, ServiceError] = 1;
If postIfInvalidNames = FALSE and LENGTH[invalidNames] > 0, then the session that's returned may not be used to post body parts.
PostOneBodyPart: PROCEDURE [session: Session, bodyPartType: BodyPartType, contents: BulkData.Source]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError, TransferError] = 8;
Called once per body part.
EndPost: PROCEDURE [session: Session, abortPost: BOOLEAN]
RETURNS [messageID: MessageID]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError, TransferError] = 9;
Terminates a session initiated by BeginPost.
Retrieval Slot Procedures
BeginRetrieval: PROCEDURE [deliverySlot: Name, credentials: Credentials, verifier: Verifier]
RETURNS [session: Session]
REPORTS [AccessError, AuthenticationError, OtherError, ServiceError] = 2;
Initiates retrieval of one or more messages via the delivery slot. The returned session is to be used in a series of calls to the operations below.
RetrieveEnvelope: PROCEDURE [session: Session]
RETURNS [empty: BOOLEAN, envelope: Envelope]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError] = 5;
Begins delivery of the message at the head of the delivery slot queue identified by 'session'. This operation is legal after BeginRetrieval or RetrievalAcknowledge. If 'empty' is TRUE, the delivery slot has no messages to deliver.
RetrieveContent: PROCEDURE [content: BulkData.Sink, session: Session]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError, TransferError] = 4;
Receives the content of the message at the head of the slot queue implied by 'session'. This operation is legal only directly after RetrieveEnvelope.
AbortRetrieval: PROCEDURE [session: Session]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError, TransferError] = 3;
Aborts delivery of the message at the head of the delivery slot queue implied by 'session'. This operation is legal following either RetrieveContent (normal case) or RetrieveEnvelope (if content is not wanted)
EndRetrieval: PROCEDURE [session: Session]
REPORTS [AuthenticationError, OtherError, SessionError, ServiceError, TransferError] = 6;
Terminates a retrieval session initiated by BeginRetrieval. This operation is legal directly after BeginRetrieval, or RetrievalAcknowledge.
MailPoll: PROCEDURE [deliverySlot: Name, credentials: Credentials, verifier: Verifier]
RETURNS [mailPresent: BOOLEAN]
REPORTS [AccessError, AuthenticationError, OtherError, ServiceError] = 7;
Checks for mail at the delivery slot.
Remote Errors
AccessError: ERROR [problem: AccessProblem] = 0;
AccessProblem: TYPE = {
accessRightsInsufficient(0), -- the user doesn't have access
accessRightsIndeterminate(1), -- cannot determine whether the user has access
deliverySlotInUse(2), -- delivery slot in use ... sharing not allowed
noSuchDeliverySlot(3), -- no delivery slot for this recipient at this server
deliverySlotIndeterminate(4), -- cannot resolve name at the clearinghouse
wrongService(5) -- the wrong service was asked about that delivery slot
};
AuthenticationError: ERROR [problem: Authentication.Problem] = 1;
InvalidRecipients: ERROR [nameList: InvalidNameList] = 3;
ServiceError: ERROR [problem: ServiceProblem] = 4;
ServiceProblem: TYPE = {
cannotAuthenticate(0), -- generally, an Authentication.CallProblem on the server
serviceFull(1), -- this operation cannot be accepted
serviceUnavailable(2), -- the service is unavailable to network clients
mediumFull(3) -- insufficient space to accept posted message
};
TransferError: ERROR [problem: TransferProblem] = 5;
TransferProblem: TYPE = {
aborted(0) -- the transfer was aborted by the source or sink
};
OtherError: ERROR [problem:OtherProblem] = 6;
OtherProblem: TYPE = {
cantExpedite(0),
the operation cannot be invoked by ExpeditedCourier
malformedMessage(1),
this error is raised if, for example, the message body parts don't correspond to the table of contents or if duplicate or illegal envelope items are specified in the optionalEnvelopeData passed to BeginPost
incorrectContentsSize(2),
the contentsSize specified was off by more than the allowable error (currently 25 pages)
last(65535) -- late errors will be added to the protocol here
};
SessionError: ERROR [problem: SessionProblem] = 7;
SessionProblem: TYPE = {
invalidHandle(0), -- the session presented was not valid
wrongState(1) -- the requested operation is not legal following the preceding operations.
};
Bulk Data Formats
Bulk data is used as defined in the Addenda to Standards, XSIS 138301. That is, the transfer simply consists of a series of packets, the last of which has end-of-message set to TRUE (if the transfer was successful). No additional structuring of the data is needed.
END.