courier.tbl.me

早期freebsd实现

c c
l l.
File	Contents

Example1_defs.h	scope widening macros (includes Example1.h)
Example1.h	definitions, typedefs, and constant declarations
Example1_support.c	routines to map between C and Courier
Example1_server.c	server main program and support routines
Example1_client.c	client routines to support applications calling Example
.TE
.)b
.pp
The header file
.i "Example1_defs.h"
should be included via
.sp
	#include ``Example1_defs.h''
.sp
in all user-written parts of the Courier program
(i.e., the implementations of the client program and server procedures.)
.pp
The 
.i "\fB-I\fIinclude-directory"
switch may be used on the command line of
.i xnscourier
to establish a search path for Courier specification files named in a
DEPENDS UPON clause. By default, the compiler looks first in the current
directory followed by the courier-description-file named in the 
.i /etc/Courierservices
file.
.sh 2 "Calling Remote Procedures \- Client Implementation"
.pp
A remote procedure appears to the C programmer to look almost like
a local procedure (although it typically makes use of resources not
available on the local machine or else runs many times slower
than would a local procedure).  A C client program (i.e. the caller
of a remote procedure) actually calls a stub function generated by
the courier compiler, which in turn executes the code necessary to
invoke the corresponding procedure on the remote machine.  
.pp
Before calling the remote procedure it is necessary to establish a
Courier SPP connection (in the process binding a local socket to
a remote machine).  This may be done by the calling the function
CourierOpen(), passing it as argument a structure identifying the remote
host.  This structure
is of type ``ns_addr''
as defined in the include file
.i "#include <netns/ns.h>" .
CourierOpen() returns an anonymous pointer
(of type CourierConnection*) to a structure containing
the socket to be used for this courier call, which should be passed
to each remote procedure to be executed on the particular remote host.
CourierOpen() returns NULL if there is a problem opening an SPP connection
to the host specified.
.pp
For low-level access to ns_addr structures,
the procedure getXNSaddr() is available, taking a string in the form
``network#a1.a2.a3.a4.a5.a6#socket'' (where all numbers are hex) or 
``networkhigh-networklow#d1-d2-d3-d4#socket'' (where all numbers are
3-digit decimal numbers)
and returning a pointer to the
corresponding ns_addr structure.  This result may then be passed as the
argument to CourierOpen().
More normally, the user will have a string in the form of an NS address,
e.g. ``jqj:computer\ science:cornell-univ''.  This string can be
coerced into a Clearinghouse ObjectName, then used in a Clearinghouse-based
lookup to find the corresponding address:
.sp 1
.nf
	Clearinghouse2_ObjectName hobj, hdefault;
	struct ns_addr * host;
	char * string;

	CH_NameDefault(&hdefault);	/* get defaults */
	hobj = CH_StringToName(string, &hdefault);
	host = CH_LookupAddr(hobj, 0);	
.fi
.sp 1
.pp
The SPP connection may be reused by multiple RPCs destined for the same
host, even if the procedures are part of different remote programs.  However,
the SPP connection may not be reused while an RPC is outstanding; thus,
if you need to issue a Courier call during a BDT transfer, you will need
to obtain a second CourierConnection.
.pp
The client then calls the compiler-generated stub function to invoke
the remote procedure.  This stub
function takes at least 2 arguments:
.ip  (1)
The pointer returned from CourierOpen().
If the SPP connection does not
currently exist (i.e. has been closed by the server)
it is reopened for this call.
.ip (2)
A pointer to a user-supplied function which will be used if a Bulk Data
Transfer is required (see the section on BDT below); if this remote
procedure does not involve Bulk Data Transfer, then the function pointer
should be 0 or NULL.
.ip (3...)
One additional argument corresponding to each parameter in the Courier
language description of this procedure.
.pp
The remote procedure returns in one of 2 ways:  either it returns
normally, passing back a structure corresponding to the RETURNS parameters
specified in the procedure description, or it signals an error which
may be caught using the DURING ... HANDLER mechanism described in
.i except(1) .
.pp
A Courier procedure is allowed to return multiple results, a language feature
not easily mapped into C.  To provide this functionality, all UNIX
courier remote procedures actually return a structure
containing the procedure results.  Thus, for a procedure named
Foo, declared
.sp 1
	Foo: PROCEDURE [ ] RETURNS [str: STRING];
.sp 1
the C function Foo would return a structure of type FooResults, declared
.sp 1
.nf
	typedef struct {
		String str;
	} FooResults;
.fi
.fi
.pp
Instead of returning a value of type determined by the RESULTS clause
of a PROCEDURE declaration, a Courier remote procedure call may return
a reject message indicating the remote system's inability to even
attempt a remote operation, or an abort message raising a remote error,
i.e. reporting the operation's failure.  Reject and abort messages are
handled by a signalling mechanism  or if uncaught cause termination of
the client program.  For example, a client calling the remote procedure
defined by
.sp 1
.nf
	NoSuchFile: ERROR = 0;
	OtherError: ERROR [ errorstring: STRING ] = 1;
	Example: PROCEDURE [ ] REPORTS [ NoSuchFile, OtherError ];
.fi
.sp 1
might be coded as
.sp 1
.nf
	conn = CourierOpen(destaddr);
	DURING Example(conn,NULL)
	HANDLER switch(Exception.Code) {
	case REJECT_ERROR:
		fprintf(stderr,"Remote reject.\en");
		exit(1);
	case NoSuchFile:
		fprintf(stderr,"No such file\en");
		break;
	case OtherError:
		fprintf(stderr,"Remote error %s\en",
			CourierErrArgs(OtherErrorArgs,errorstring) );
		break;
	case PROTOCOL_VIOLATION:
	case INTERNAL_ERROR:
		fprintf(stderr,"Local internal error %s\en",
			Exception.Message);
		break;
	default:
		fprintf(stderr,"Unknown error, type %d\en",
			Exception.Code);
	}	
	END_HANDLER
.fi
.sp 1
The error value, Exception.code, will be one of (1) ``REJECT_ERROR'',
which indicates a REJECT message from the remote server, (2) a program-defined
ERROR value (offset by ERROR_OFFSET), (3) or ``INTERNAL_ERROR'' 
or ``PROTOCOL_VIOLATION''
indicating
a serious internal error in the Unix courier implementation; in the third
case, a string is available as Exception.Message.
Both errors and rejections may have arguments, which can be accessed
within a handler as a struct pointed to by Exception.Message.  For
programmer convenience a macro, CourierErrArgs, is defined, taking
as arguments the typedef defining the current error's arguments 
and the name of the argument to be accessed; this macro may be used
only within an error handler.
For rejection messages, the type should be ``rejectionDetails,''
as defined on page 25 of the Courier spec.
.pp
When done with a particular remote connection, the client should call
CourierClose() with argument the pointer returned from CourierOpen()
to free the socket and cleanly close the connection.
.pp
The client program should be loaded with 
.i "Example1_client.o" ,
.i "Example1_support.o" ,
and -lcourier (the XNS Courier library)
to produce an executable program.
.sh 2 "Writing a Courier Server"
.pp
The Courier protocol specifies a standard for communicating
parameters and results which has been adhered to in this
implementation.
It also specifies an initial connection protocol
and a format for messages.
.pp
There is a single Courier Daemon per UNIX machine whose function
is to listen on a well-known XNS port for Courier interface activation
requests.
A request contains the number of the Courier program
whose server is to be activated, and its version number.  These two
numbers are used as a key in the file 
.i /etc/Courierservices
to identify
the executable file associated with the particular courier program.
.i /etc/Courierservices
consists of a sequence of lines of the form
.sp 1
	program-name  program-number  version  courier-description-file  server-binary-file
.sp 1
The daemon
either spawns the executable file
or replies with a reject message.  Note that each incoming remote procedure
call may be serviced by a separate UNIX process.
This implies that connection-oriented services (services which consist of a
sequence of related procedure calls) must be implemented by maintaining
the state of connections in a file.
.pp
The executable file containing the server for a particular remote
program consists of a main program generated by the courier compiler
which interprets CALL messages from the remote client and calls
one or more user-written functions to implement the
courier procedures.
.pp
Given a courier specification for the remote program Example containing
remote procedure Example,
the server functions (including the C function Example and any support
routines needed)
should be loaded with 
.i "Example1_server.o" ,
.i "Example1_support.o" ,
and -lcourier
to produce the server process that will be invoked whenever
an activation request arrives.
.pp
A server function receives an argument list similar to that passed by
a client to a remote procedure.  The first two arguments in the
parameter list should be ignored; each succeeding argument corresponds
to one parameter in the courier declaration.
.pp
To return from a server function you must return a structure containing
the results of the procedure.  If this structure contains pointers (e.g.
Strings) you should insure that the data pointed to is allocated
staticly or on the heap rather than on the stack.
You must not call exit(3) from within the server function; doing so will
cause the client (remote caller) to hang indefinitely waiting for a
reply.
.pp
To abort a server function, returning an error code, use the
``raise(code, msg)''
library function, with arguments the error code and either NULL (if the
error takes no arguments) or a pointer to a structure containing the
arguments to the error.  Raise causes a longjump out of the function
directly to the handler, and thence to the remote procedure caller.
For example, to return the OtherError message defined above one might code
.sp 1
.nf
	OtherErrorArg randomerr;
	. . .
	randomerr.errorstring = sys_errlist[errno]);
	raise(OtherError,(char*) &randomerr);
.fi
.sp 1
.pp
When a server function returns to its main program caller the main()
sends the appropriate RETURN or ABORT message to the remote client,
and does an exit(0).  The server then holds the connection for up to 90 
seconds waiting for another Courier call to arrive on the same SPP
stream.
.sh 2 "Dynamic Allocation"
.pp
One additional 
.i caveat 
is necessary when using Courier remote procedure calls from C:  C does not
have garbage collection, so you should free any dynamically allocated storage
when you are done with it.  In general, top level Courier objects are
always allocated from the stack or statically; however, strings and sequences
within an object are generally allocated from the heap using malloc().
.pp
A client program which calls the remote procedure Foo defined above,
returning a STRING,
actually has returned to it a C struct containing a pointer to an array
of malloced characters.  When done with this string, the program may free
it by calling clear_FooResults() with argument the address of the
result returned by the call to Foo.  Thus:
.sp 1
.nf
	FooResults result;
	. . .
	result = Foo(conn,NULL);
	. . .
	printf("result was %s\n",result.str);
	clear_FooResults(&result);
.fi
.sp 1
.sh 1 "Using Bulk Data Transfer"
.pp
.sh 2 "Overview"
.pp
When a Courier program needs to transfer an arbitrary amount of
information as an argument or result of a Courier procedure, the
procedure is usually defined to have an argument of type ``BulkData.Sink''
or ``BulkData.Source'' (and a ``DEPENDS UPON BulkData''
is included in the program).
The argument is a ``source'' if it is information transferred from caller
to server (as though a procedure argument), a ``sink'' if it is
information transferred from server to caller (as though a procedure
result).  In this
implementation, a Courier procedure may have at most one such argument,
which must have the value null or immediate.
In a Courier call, the bulk data is transmitted in a special way,
multiplexed into the same data path as control messages
between the arguments and the results.
.pp
The BDT user should include in the 
.i ".cr"
file a ``DEPENDS UPON BulkData (0) VERSION 1'', then reference these
arguments as BulkData.Source and BulkData.Sink in PROCEDURE
declarations.
The declaration of a Courier PROCEDURE can then indicate a bulk
data transfer by including in its formal argument list a variable
of type BulkData.Source or BulkData.Sink
as appropriate.
The corresponding parameter to the C procedure will be of type
BulkData1_Descriptor.
.sh 2 "Coding a Client"
.pp
To use Bulk Data in a client program, the Courier definition of the
procedure must include one BulkData.Source or BulkData.Sink parameter.
As the actual argument to the call, the C client passes a constant,
either BulkData1_immediateSource, BulkData1_immediateSink, BulkData1_nullSource, 
or BulkData1_nullSink as appropriate.  The client
also specifies a pointer to a user-supplied function as the second
argument to the remote procedure.
Courier sets up the transaction, then calls the supplied function with
one argument, the pointer returned by CourierOpen() describing the
SPP socket on which to write (if a source argument) or read
(if a sink) the bulk data. 
.pp
To complete the transaction normally, the
function should send packets of SPP data terminated by
an end-of-message (if writing) or read up to but not beyond an
end-of-message (if reading), and should return normally to its caller.
To do so, it should call the procedures BDTread(), BDTwrite(), or 
BDTclosewrite()
as appropriate.  BDTread() and BDTwrite() take arguments analogous to read()
and write() except that instead of a file descriptor they accept the SPP
descriptor returned by CourierOpen(); their arguments are thus
(1) the pointer to the SPP data structure,
(2) a pointer to an array of characters (the IO buffer),
and (3) a count;
they return the number of characters actually read or written.
.pp
The UNIX program can finish a write transfer by calling BDTclosewrite() or
BDTabort(), each with the SPP descriptor as argument.
BDTclosewrite() produces an SPP end-of-message, while BDTabort() instructs
Courier to discard any buffered data and
send a Bulk Data Abort to abort the transaction.  A read transfer may also be
prematurely ended by calling BDTabort().
.sh 2 "Coding a Server"
.pp
Writing a server that uses BDT
is similar to writing the BDT function in a caller.
The server is passed a BulkData.Source or BulkData.Sink (the two are
indistinguishable at run time).
The server routine should check to make sure that the source or sink
is of type null or immediate (active and passive descriptors are not
supported in this implementation) by means of code such as:
.sp 1
.nf
Foo(bdtconnection,ignoredarg,..., s, ...)
	CourierConnection *bdtconnection;
	BulkData1_Sink s;
	. . .
	switch (s.designator) {
	case active:
	case passive:
		/* can't raise BulkData1_InvalidDescriptor, so */
		raise(someerror);
	case null:
		/* handle null transfer */
		break;
	case immediate:
		/* handle normal, i.e. immediate, transfer */
		break;
	}
.fi
.sp 1
Note that the BDT error InvalidDescriptor cannot be used unless the
procedure declaration explicitly notes that this is a valid REPORTS error
type.  Normally, each courier program defines its own error to be reported
on BDT problems.
.pp
Use the first argument to the server procedure as the handle on the
BDT connection.
As with a client BDTabort() may
be used to send abort messages.
.sh 2 "Sending Bulk Data"
.pp
Sending bulk data, either as client or server, is quite
straightforward.  Use the supplied procedure BDTwrite(), whose
semantics are similar to write().  BDTwrite() will return -1
if an error occurs or an abort from the listener is received; in this
case, the sender should immediately cease transmitting BDT data, and
should instead call BDTabort(). 
Typical code to send data on ``bdtconnection'',
in this case read from a buffered file open
as ``source,'' might appear as:
.sp 1
.nf
	CourierConnection *bdtconnection;
	FILE *source;
	int count;
	char buffer[SPPMAXDATA];
	...
	while ( (count = fread(buffer,1,SPPMAXDATA,source)) > 0 &&
		BDTwrite(bdtconnection,buffer,count) >= 0 )
		;
	if (count <= 0)	/* succsfull transfer */
		BDTclosewrite(bdtconnection);
	else
		BDTabort(bdtconnection);
.fi
.sp 1
.pp
Each BDTwrite() transmits one packet after checking for an abort message
from the receiver.
A sender which gets an abort from a remote receiver must immediately
stop transferring data and instead must echo an abort via BDTabort()
to acknowledge the end of the transfer.
.pp
Also, for efficiency's
sake it is desirable to write packets as near as possible to the
nominal maximum length of an SPP packet; this suggests a buffer length of
534 bytes.  For programmer convenience, the file