SunRPC.mesa
Copyright Ó 1992 by Xerox Corporation. All rights reserved.
Demers, September 20, 1987 11:59:44 am PDT
For Cedar10.0
Chauser, January 7, 1992 3:03 pm PST
DIRECTORY
Basics USING [Card16FromH, Card32FromF, FFromCard32, FWORD, HFromCard16, HWORD, UnsafeBlock],
Rope USING [ROPE],
SunRPCAuth USING [Flavor, Conversation]
;
SunRPC: CEDAR DEFINITIONS
IMPORTS Basics
~ {
Types
ROPE: TYPE ~ Rope.ROPE;
UnsafeBlock: TYPE ~ Basics.UnsafeBlock;
Handle: TYPE ~ REF Object;
Object: TYPE ~ RECORD [
xid: CARD32 ¬ 0,
authFlavor: SunRPCAuth.Flavor,
authData: REF,
procs: ClientProcs,
flavor: ATOM,
flavorData: REF
];
ClientProcs: TYPE ~ REF ProcsObject;
ProcsObject: TYPE ~ RECORD [
destroy: PROC [h: Handle],
sendCallAndReceiveReply: PROC [h: Handle, timeoutMsec: CARD, retries: CARD] ,
receiveAnotherReply: PROC [h: Handle, timeoutMsec: CARD],
releaseReply: PROC [h: Handle],
bytesRemaining: PROC [h: Handle] RETURNS [bytes: CARDINAL],
getByte: PROC [h: Handle] RETURNS [byte: BYTE],
skipBytes: PROC [h: Handle, bytes: CARDINAL],
getAlign: PROC [h: Handle],
getH: PROC [h: Handle] RETURNS [hword: Basics.HWORD],
getF: PROC [h: Handle] RETURNS [fword: Basics.FWORD],
unsafeGetBlock: UNSAFE PROC [h: Handle, block: UnsafeBlock],
getBlock: PROC [h: Handle, block: REF TEXT, startIndex: CARDINAL ¬ 0, count: CARDINAL ¬ CARDINAL.LAST],
putByte: PROC [h: Handle, byte: BYTE],
putAlign: PROC [h: Handle, padValue: BYTE ¬ 0],
putH: PROC [h: Handle, hword: Basics.HWORD],
putF: PROC [h: Handle, fword: Basics.FWORD],
unsafePutBlock: UNSAFE PROC [h: Handle, block: UnsafeBlock],
putBlock: PROC [h: Handle, block: REF READONLY TEXT, startIndex: CARDINAL ¬ 0, count: CARDINAL ¬ CARDINAL.LAST],
prepareForMessage: PROC [h: Handle] -- called from class implementations
];
Conversation: TYPE ~ SunRPCAuth.Conversation;
Client Handles
GetFlavor: PROC [h: Handle]
RETURNS [flavor: ATOM];
This interface defines the behavior of flavors:
$UDP -- RPC using UDP
$networkStream -- RPC using streams from NetworkStream
$reader -- unmarshalling from a RefText
$writer -- marshalling to a RefText
Other interfaces could be created and implemented to allow other flavors.
Destroy: PROC [h: Handle] ~ INLINE {
h.procs.destroy[h];
};
Destroy a client handle.
Clients
StartCall: PROC [h: Handle, c: Conversation, pgm, version, proc: CARD];
Prepare to serialize the arguments.
On return, h is ready to put the arguments with PutXXX[h, ...].
SendCallAndReceiveReply: PROC [h: Handle, timeoutMsec: CARD¬CARD.LAST, retries: CARD¬0] ~ INLINE {
h.procs.sendCallAndReceiveReply[h, timeoutMsec, retries];
};
Send the arguments and wait for the reply.
timeoutMsec and retries are implemented only for $UDP handles.
On return, h is ready to get the results with GetXXX[h].
! Error[<any>]
ReceiveAnotherReply: PROC [h: Handle, timeoutMsec: CARD ¬ CARD.LAST] ~ INLINE {
h.procs.receiveAnotherReply[h, timeoutMsec]
};
Wait for another reply. Used for broadcast-based protocols.
timeoutMsec is implemented only for $packet-flavored handles.
On return, h is ready to get the results with GetXXX[h].
! Error[$timeout | $protocolError | $wrongRPCVersion | $wrongProg | $wrongProgVersion]
ReleaseReply: PROC [h: Handle] ~ INLINE {
h.procs.releaseReply[h];
};
Free some resources associated with the handle.
The next StartCall[h] or Destroy[h] does an implicit ReleaseReply[h] if you forgot it.
Servers
Server: TYPE ~ REF ServerObject;
ServerObject: TYPE ~ RECORD [
pgm: CARD32,
version: CARD32,
clientData: REF,
serverProc: ServerProc,
dead: BOOL ¬ FALSE,
mgtProcs: ServerMgtProcs ¬ NIL,
flavor: ATOM ¬ $unbound,
flavorData: REF ¬ NIL
];
ServerMgtProcs: TYPE ~ REF ServerMgtProcsObject;
ServerMgtProcsObject: TYPE ~ RECORD [
destroyServer: PROC[ s: Server ]
];
DestroyServer: PROC [s: Server] ~ INLINE {
s.mgtProcs.destroyServer[s];
};
ServerProc: TYPE ~ PROC [h: Handle, c: Conversation, proc: CARD, clientData: REF]
RETURNS [doReply: BOOL, replyTimeToLive: CARDINAL];
On entry, h is ready to get the arguments with SunRPC.GetXXX[h].
If doReply=FALSE, no reply message will be sent.
See the various transport-specific interfaces (e.g. SunRPCOnUDP, SunRPCOnNetworkStream) for fine points about doReply and replyTimeToLive.
StartReply: PROC [h: Handle];
StartReply is called at the beginning of a ServerProc prior to marshalling any results.
On return, h is ready to put the results with PutXXX[h, ...].
Serializing / Deserializing
BytesRemaining: PROC [h: Handle] RETURNS [bytes: CARDINAL] ~ INLINE {
RETURN [h.procs.bytesRemaining[h]]
};
Return number of bytes remaining to be read by GetXXX[h].
GetByte: PROC [h: Handle] RETURNS [byte: BYTE] ~ INLINE {
RETURN [h.procs.getByte[h]]
};
SkipBytes: PROC [h: Handle, bytes: CARDINAL];
GetAlign: PROC [h: Handle] ~ INLINE {
h.procs.getAlign[h]
};
GetH: PROC [h: Handle] RETURNS [hword: Basics.HWORD] ~ INLINE {
RETURN [h.procs.getH[h]]
};
GetCard16: PROC [h: Handle] RETURNS [card16: CARD16] ~ INLINE {
RETURN [Basics.Card16FromH[GetH[h]]] };
GetInt16: PROC [h: Handle] RETURNS [int16: INT16] ~ INLINE {
RETURN [LOOPHOLE[Basics.Card16FromH[GetH[h]]]] };
GetF: PROC [h: Handle] RETURNS [fword: Basics.FWORD] ~ INLINE {
RETURN h.procs.getF[h]
};
GetCard32: PROC [h: Handle] RETURNS [card32: CARD32] ~ INLINE {
RETURN [Basics.Card32FromF[GetF[h]]] };
GetInt32: PROC [h: Handle] RETURNS [int32: INT32] ~ INLINE {
RETURN [LOOPHOLE[Basics.Card32FromF[GetF[h]]]] };
UnsafeGetBlock: UNSAFE PROC [h: Handle, block: UnsafeBlock] ~ UNCHECKED INLINE {
h.procs.unsafeGetBlock[h, block]
};
GetBlock: PROC [h: Handle, block: REF TEXT, startIndex: CARDINAL ¬ 0, count: CARDINAL ¬ CARDINAL.LAST] ~ INLINE {
h.procs.getBlock[h, block, startIndex, count]
};
GetRefText: PROC [h: Handle] RETURNS [refText: REF TEXT];
GetEphemeralRefText: PROC [h: Handle, oldBuffer: REF TEXT ¬ NIL]
RETURNS [newBuffer: REF TEXT];
Reuse "oldBuffer" if it's long enough; otherwise allocate a new one with RefText.ObtainScratch.
GetRope: PROC [h: Handle] RETURNS [ROPE];
PutByte: PROC [h: Handle, byte: BYTE] ~ INLINE {
h.procs.putByte[h, byte]
};
PutAlign: PROC [h: Handle, padValue: BYTE ¬ 0] ~ INLINE {
h.procs.putAlign[h]
};
PutH: PROC [h: Handle, hword: Basics.HWORD] ~ INLINE {
h.procs.putH[h, hword]
};
PutCard16: PROC [h: Handle, card16: CARD16] ~ INLINE {
PutH[h, Basics.HFromCard16[card16]] };
PutInt16: PROC [h: Handle, int16: INT16] ~ INLINE {
PutH[h, Basics.HFromCard16[LOOPHOLE[int16]]] };
PutF: PROC [h: Handle, fword: Basics.FWORD] ~ INLINE {
h.procs.putF[h, fword]
};
PutCard32: PROC [h: Handle, card32: CARD32] ~ INLINE {
PutF[h, Basics.FFromCard32[card32]] };
PutInt32: PROC [h: Handle, int32: INT32] ~ INLINE {
PutF[h, Basics.FFromCard32[LOOPHOLE[int32]]] };
UnsafePutBlock: UNSAFE PROC [h: Handle, block: UnsafeBlock] ~ UNCHECKED INLINE {
h.procs.unsafePutBlock[h, block]
};
PutBlock: PROC [h: Handle, block: REF READONLY TEXT, startIndex: CARDINAL ¬ 0, count: CARDINAL ¬ CARDINAL.LAST] ~ INLINE {
h.procs.putBlock[h, block, startIndex, count]
};
PutRefText: PROC [h: Handle, refText: REF READONLY TEXT];
PutRope: PROC [h: Handle, rope: ROPE];
Fold in SunRPCNumbers from PCedar2.0
Serializing / Deserializing
GetBool: PROC [h: Handle] RETURNS [BOOL];
PutBool: PROC [h: Handle, bool: BOOL];
GetInt64: PROC [h: Handle] RETURNS [INT64];
PutInt64: PROC [h: Handle, int64: INT64];
GetCard64: PROC [h: Handle] RETURNS [CARD64];
PutCard64: PROC [h: Handle, card64: CARD64];
GetReal: PROC [h: Handle] RETURNS [REAL];
PutReal: PROC [h: Handle, real: REAL];
GetDReal: PROC [h: Handle] RETURNS [DREAL];
PutDReal: PROC [h: Handle, dreal: DREAL];
Procedures for use in class implementations to manage the protocol
StartAcceptReply: PUBLIC PROC [h: Handle, acceptStat: CARD32];
StartRejectReply: PUBLIC PROC [h: Handle, rejectStat: CARD32];
GetAuth: PUBLIC PROC [h: Handle] RETURNS [flavor: SunRPCAuth.Flavor, value: REF TEXT];
PutAuth: PROC [h: Handle, flavor: SunRPCAuth.Flavor, value: REF TEXT] ;
Errors
Error: ERROR [code: ATOM];
Codes:
$outOfBufferSpace -- for PutXXX
$outOfData -- for GetXXX
$notNetworkHandle -- inappropriate use of reader or writer handle.
$unreachable
$timeout
$wrongRPCVersion
$protocolError
$badCredentials -- I can't parse them.
$wrongCredentials -- I never heard of you.
$badVerifier -- I can't parse it.
$wrongVerifier -- The verifier doesn't agree with the credentials.
$badReplyVerifier -- I can't parse it.
$wrongReplyVerifier -- Not what I expected.
$weakCredentials -- I believe who you are, but you're not privileged to do this.
$wrongProgram -- Specified program not exported by this server.
$wrongProgramVersion -- Specified program available, but not in the specified version.
$wrongProc -- Specified program and version available, but doesn't have the specified proc.
}...