![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to courier.tbl.me CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / new / xns / doc|
Return to courier.tbl.me CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / new / xns / doc |
1.1 root 1: \" $Header: courier.tbl.me,v 1.8 87/03/17 09:32:52 ed Exp $
2: \" $Header: courier.tbl.me,v 1.8 87/03/17 09:32:52 ed Exp $
3: \" $Log: courier.tbl.me,v $
4: \" Revision 1.8 87/03/17 09:32:52 ed
5: \" Added -I switch to establish search path for DEPENDS UPON files.
6: \"
7: \" Revision 1.7 86/11/22 07:12:05 jqj
8: \" small changes reflecting differences between 4.3bsd and 4.2 Maryland XNS.
9: \"
10: \" Revision 1.6 86/05/12 09:02:43 jqj
11: \" minor revisions
12: \"
13: \" Revision 1.5 85/03/26 06:30:58 jqj
14: \" Revised public alpha-test version, released 26 March 1985
15: \"
16: \" Revision 1.4 85/03/11 16:46:01 jqj
17: \" Public alpha-test version, released 11 March 1985
18: \"
19: .lg 0
20: .fo ''%''
21: .(l C
22: .ps +4
23: .b
24: XNS Courier under UNIX (4.3BSD)
25: .ps -4
26: .sp 2
27: .r
28: .he $ XNS Courier $ $Date: 87/03/17 09:32:52 $
29: J.Q. Johnson
30: Computer Science Department
31: Cornell University
32: 405 Upson Hall
33: Ithaca, NY 14853
34: .)l
35: .sh 1 "Introduction"
36: .pp
37: This document describes the implementation and use
38: of the Courier remote procedure call protocol for Berkeley UNIX
39: (version 4.3), with XNS.
40: .sp 1
41: .nf
42: .b
43: .(c
44: ********************************************************
45: Warning: this document is a DRAFT design specification.
46: It has not yet been fully implemented, and the details of
47: the interface it specifies (particularly with respect to
48: Courier servers) are subject to change. Send design
49: comments to [email protected] or [email protected].
50: ********************************************************
51: .)c
52: .r
53: .fi
54: .sp 1
55: .uh "Changes since previous revision:"
56: .np
57: Added discussion of encapsulated protocols.
58: .np
59: Added discussion of Clearinghouse library calls for finding a connection,
60: and relationship of connections to outstanding RPCs.
61: .uh "Earlier changes:"
62: .np
63: Changed names of generated file names to include version number.
64: Added discussion on scope of names vs. DEPENDS UPON modules.
65: .np
66: Users must now link Courier program ``Foo'' with Foo1_support.o.
67: .np
68: Added some discussion of freeing dynamic storage via clear_Foo.
69: .np
70: Changed
71: .i CourierOpen()
72: to take ns_addr structure rather than a string host name. Routines for
73: converting from name to address (using Clearinghouse) have not yet been
74: designed.
75: .np
76: Changed ERROR discussion to indicate that an ERROR is mapped to a long
77: with value > 65535.
78: .np
79: Changed description of BDT to reflect use of
80: .i BDTread()
81: and
82: .i BDTwrite() .
83: .np
84: Added SPPMAXDATA.
85: .np
86: Changed discussion of BulkData constants to indicate that things now
87: work correctly.
88: .sh 2 "General Description"
89: .pp
90: Courier is both a protocol and a specification language.
91: The protocol describes how remote procedures are invoked and
92: how parameters and results of various data types are transmitted.
93: The specification language, somewhat reminiscent of Mesa,
94: provides a simple way of defining the remote interfaces of distributed
95: programs.
96: .pp
97: This implementation is an attempt to allow UNIX C programmers to
98: construct distributed Courier programs to communicate with other
99: Courier implementations layered on XNS. It thus requires kernel
100: support for XNS Sequenced Packet Protocol sockets.
101: .pp
102: The simplest form of distributed program using Courier
103: consists of three parts.
104: The first is the specification,
105: written in the Courier language.
106: The specification must declare all procedures of
107: the program that will be called remotely (the
108: .i "server procedures" ).
109: The next part is the implementation, in C, of the server procedures.
110: Finally, there is the client portion of the program, also in C, which calls
111: the server procedures.
112: Note that either the client or server portion of the program may be
113: omitted if the UNIX program is designed to act with a non-UNIX
114: partner; for example, a simple printing client under UNIX might send
115: files to a Xerox laser printer using the Printing protocol published
116: and supported by Xerox.
117: .sh 2 "Acknowledgements"
118: .pp
119: Contributors to the current implementation have included
120: JQ Johnson, the primary implementor of the current version of the
121: Courier compiler under UNIX,
122: Eric Cooper, the author of the original UNIX Courier/TCP compiler,
123: Jeff Mogul, the author of the exception signalling mechanism used
124: here to handle abort and reject messages,
125: James O'Toole, Chris Torek, and Mark Weiser,
126: the authors of the 4.2BSD version of UNIX kernel support for XNS,
127: Keith Sklower, the author of the present (4.3BSD) version of UNIX kernel support,
128: Lee Moore, and Bill Nesheim.
129: .pp
130: Some of the software is copyright 1984 by Eric Cooper, and is for
131: research use only; it may be freely distributed but may not be
132: sold as a commercial product.
133: .sh 2 "References"
134: .pp
135: This document assumes familiarity with the Courier language,
136: details of which may be found in
137: the Courier protocol definition,
138: .i "Courier: The Remote Procedure Call Protocol" ,
139: Xerox System Integration Standard 038112,
140: December 1981, and ``Appendix F, Bulk Data Transfer,'' Xerox System
141: Integration Standard 038112 Add. 1, October 1982.
142: However, for reference purposes, a grammar for the Courier language
143: may be found in the appendix to this document.
144: .pp
145: Users of Bulk Data Transfer will need to interact with SPP
146: (Sequenced Packet Protocol)
147: streams, and may wish to see
148: .i "Internet Transport Protocols" ,
149: Xerox System Integration Standard 028112, December 1981.
150: .pp
151: Those interested in the workings of UNIX networking might consult
152: ``A 4.2bsd Interprocess Communications Primer,''
153: (DRAFT of March 11, 1983), by Samuel J. Leffler, Robert S. Fabry, and
154: William N. Joy, and the
155: ``4.2BSD System Manual,''
156: (Revised July, 1983), by William Joy
157: .i "et al" .
158: .pp
159: This document is also supplemented by various UNIX manual pages, notably
160: .i "xnscourier(3) " ,
161: and
162: .i "except(3)" .
163: .sh 2 "Software and Hardware Dependencies"
164: .pp
165: This package requires the following software to operate:
166: .(l
167: 4.3BSD (currently tested only for VAX and Gould versions)
168: PCC, 4.3BSD version (probably\-limited testing has been done with Tartan C)
169: .)l
170: .pp
171: To communicate with Xerox products you will need an Ethernet
172: interface. Most of the existing example applications depend heavily on
173: the existence of a Xerox Clearinghouse somewhere on the local network.
174: .sh 1 "The Courier Specification Language"
175: .pp
176: The Courier specification language is documented (loosely) in the Xerox
177: ``Courier: The Remote Procedure Call Protocol.'' Our compiler
178: implements a large subset of the specification. Note that the embedding
179: of Courier constructs in a message or bit stream is usually irrelevant to the
180: applications programmer, who need only be concerned with the semantics
181: of the Courier datatypes. The courier compiler and runtimes translate
182: Courier datatypes into more easily managed C constructs and handle the
183: protocol of communication with the remote system.
184: .pp
185: This implementation places several restrictions on the specifications
186: it will accept:
187: .np
188: No forward references are permitted in the courier
189: specification. The user must reorder type specifications so that all
190: types and constants are defined before they are used.
191: Special provisions are made for recursive type declarations of the form
192: typically found in Bulk Data ``StreamOf'' declarations; see the
193: discussion of BDT below for details. General recursive declarations,
194: e.g. that of the Filing ``Filter,'' are not supported.
195: .np
196: The Courier specification is unclear as to lexical issues,
197: name scope, and name overloading.
198: In the current compiler, names should contain only upper and lower case
199: letters or digits. Also, all constants, types, and
200: enumeration tags within a module should have distinct names. Enumeration
201: tag names are currently global; thus, different enumeration types, even
202: in different modules, may not have the same tags.
203: .np
204: Constants of type CHOICE are not fully supported. In particular, they
205: are allowed only if the active arm of the choice is a nill record.
206: .np
207: Constants of type SEQUENCE are not supported. Constants of type ARRAY
208: (which have the same syntax as SEQUENCE constants) are supported, but are
209: not rangechecked; ``Vect: ARRAY 10 OF INTEGER = {1,2,3}'' is accepted,
210: though illegal.
211: .np
212: This implementation supports DEPENDS UPON and
213: referenced types and constants. However, the semantics of referenced
214: enumeration constants is unclear. Also, this implementation
215: does not support recursive dependencies.
216: .lp
217: We think we've eliminated all other restrictions, but we're probably wrong.
218: .sh 2 "Predefined types"
219: .pp
220: The following typedefs correspond to predefined Courier types:
221: .(b
222: .TS
223: c c c
224: l l l.
225: Courier type C typedef Implemented (on VAX) as
226:
227: BOOLEAN Boolean char (0==TRUE, 1==FALSE)
228: CARDINAL Cardinal unsigned short
229: LONG CARDINAL LongCardinal unsigned long
230: INTEGER Integer short
231: LONG INTEGER LongInteger long
232: STRING String char*
233: UNSPECIFIED Unspecified unsigned short
234: LONG UNSPECIFIED LongUnspecified unsigned long
235: .TE
236: .)b
237: Note that the representations of these types as seen by the applications
238: programmer are quite different from those sent over a Courier SPP connection.
239: For example, on the VAX a Cardinal's bytes are swapped before being
240: sent out in network byte order. A UNIX String corresponds to a pointer to
241: a null-terminated array of characters while a Courier serialized STRING
242: contains a count directly followed by an array of characters. Note
243: in particular that this implementation does
244: not support Courier STRINGs containing the ascii character NUL.
245: .sh 2 "Constructed types"
246: .pp
247: The Courier enumeration, array, and (non-null) record types
248: correspond to C enumerations, arrays, and structures respectively.
249: The Courier null record corresponds to an int.
250: .pp
251: The Courier sequence and choice types
252: pose some problems when they are mapped into C.
253: This is because an object of one of these types
254: must contain run-time information (the length of the sequence
255: or which choice is present)
256: that is implicit in Courier, but must be made explicit
257: in C.
258: Furthermore, the C programmer must bear the responsibility of keeping
259: this information consistent.
260: .pp
261: A sequence type is mapped into a structure consisting
262: of a Cardinal called
263: .i "length" ,
264: and a pointer to the sequence elements called
265: .i "sequence" .
266: The consistency requirement is that
267: .i "length"
268: indicate the number of elements in the array pointed to
269: by
270: .i "sequence" .
271: .pp
272: A choice type is mapped into a structure consisting
273: of an enumeration element called
274: .i "designator" ,
275: and a union of all the possible choices.
276: The designator is of the enumeration type defined
277: (implicitly or explicitly)
278: in the declaration of the choice type.
279: If this enumeration consists of elements
280: .i A ,
281: .i B ,
282: and
283: .i C ,
284: then the choices are accessible as
285: .i A_case ,
286: .i B_case ,
287: and
288: .i C_case .
289: The consistency requirement is that
290: .i "designator"
291: contain the enumeration value corresponding to
292: which choice currently occupies the union.
293: .sh 2 "Constants"
294: .pp
295: The Courier specification is silent on the precise representations of
296: numbers and strings. In this implementation, numbers may be represented
297: as an optional minus sign followed by a
298: sequence of decimal digits or a sequence of octal digits followed
299: by ``B''. A constant of type STRING
300: is represented by a sequence of characters enclosed in
301: double quotation marks; it has the same restrictions as a C literal string (no
302: embedded newlines, use ``\e'' as a prefix character, etc.) except that double
303: double quotes are permitted to indicate quotations inside the string.
304: .sp 1
305: .nf
306: minInt: INTEGER = -2147483648; -- or 20000000000B --
307: lastCard: CARDINAL = 177777B; -- or 65535 --
308: quotedName: STRING = "my name is \"jqj""\en";
309: .fi
310: .sp 1
311: .pp
312: Although the Courier language allows constants of
313: any type to be declared,
314: it is difficult to define constants of constructed types
315: in C programs.
316: This implementation normally handles constants by creating
317: static variables initialized to the values of the (possibly structured)
318: constants. The technique is not in general possible for structured
319: constants of type CHOICE
320: since they are implemented as C ``unions'', so this implementation does not
321: support constants which contain a non-null CHOICE. As a special case,
322: constants whose selected variant is a null record are allowed, e.g.
323: .sp 1
324: myImmediate: BulkData.Immediate = immediate [];
325: .sp 1
326: .sh 2 "Procedures"
327: .pp
328: PROCEDURE constants correspond to C functions plus a numeric jump table
329: index used in serialization of procedure calls on the network.
330: Procedure declarations may include argument lists, result lists, and
331: error lists. The argument list of the corresponding C function
332: contains one parameter for each parameter specified in the declaration,
333: but is
334: expanded by the addition of 2 parameters (see below). The result list
335: specifies a C structure to be returned by the C function containing the
336: results; for a procedure, Foo, this result list is of type FooResults.
337: Thus, a procedure declared
338: .sp 1
339: Example: PROCEDURE [ ] RETURNS [ a: Foo, b: Baz ] = 0;
340: .sp 1
341: would be implemented by a C function with no arguments
342: returning a structure of type ExampleResults with definition
343: something like
344: .sp 1
345: .nf
346: typedef struct {
347: Foo a;
348: Baz b;
349: } ExampleResults
350: .fi
351: .sp 1
352: Note that Foo and Baz might be arbitrarily complex structures;
353: see ``Constructed Types'' above.
354: .pp
355: Importing a PROCEDURE from a DEPENDS UPON module imports only its jump
356: table index.
357: .sh 2 "ERROR constants"
358: .pp
359: An ERROR constant corresponds to a defined numeric value, and possibly
360: to a C structure describing its argument list. For example,
361: .sp 1
362: OtherError: ERROR [ errorstring: STRING ] = 1;
363: .sp 1
364: corresponds approximately to the C declarations:
365: .sp 1
366: .nf
367: #define OtherError (1+ERROR_OFFSET)
368: typedef struct {
369: String errorstring;
370: } OtherErrorArgs;
371: .fi
372: .sp 1
373: Note that ERROR values must be specified in the range 0 to 65535, but
374: that they produce a symbol which appears to the C programmer
375: with values of type int
376: in the range 65536 to 131171 (in some contexts, the user may wish to
377: treat C error values in the range 0 to 65535 as Unix error numbers).
378: The structure corresponding to the error
379: may be useful in creating and referencing error arguments
380: in C functions.
381: .sh 2 "Scope of Names"
382: .pp
383: Given a courier program beginning
384: .sp
385: Example : PROGRAM 537 VERSION 1 =
386: .sp
387: types and constants declared in this program belong to the module ``Example1'';
388: Their full names have prefixed to them the program name and version number.
389: Given the declaration of ``minInt'' above, the XNS Courier compiler actually
390: produces a header file (here
391: .i Example1.h )
392: containing the C declaration:
393: .sp 1
394: .nf
395: static Integer Example1_minInt = {-2147483648};
396: .fi
397: .sp 1
398: .pp
399: This prefixing implies that a C programmer may refer to several different
400: remote Courier programs without risk of name collision.
401: For programmer convenience a second header file (here
402: .i Example1_defs.h )
403: is also created by the compiler containing macro definitions which widen
404: the scope to ``Example1'' and allow the programmer to refer to types and
405: constants without explicit qualification. The programmer may include
406: whichever header file he prefers.
407: .pp
408: Note that types and constants obtained from a DEPENDS UPON inclusion must
409: be referenced using fully qualified form. Note also that structure members,
410: procedure arguments, and enum tags are not currently qualified; beware
411: potential name conflicts!
412: .sh 1 "Running the Courier Compiler"
413: .pp
414: The specification file is expected to have the extension
415: .i ".cr" .
416: Consider the following skeletal Courier program definition:
417: .sp
418: Example : PROGRAM 537 VERSION 1 = BEGIN ... END.
419: .sp
420: The name of this Courier program is ``Example''; it is version 1.
421: By convention, this specification would stored in the file
422: .i "Example1.cr" .
423: The ``537'' in this example is illustrative only;
424: the program number is uniquely allocated from the range of LongCardinals
425: by Xerox. See Appendix B of the Courier standard for program number
426: assignment procedures.
427: .pp
428: The first step is to use the Courier compiler on the specification.
429: Assuming
430: .i "xnscourier"
431: is in your path (it is
432: .i "/usr/new/xnscourier"
433: on the Berkeley distribution), type
434: .sp 1
435: xnscourier Example1.cr
436: .sp 1
437: If there are no errors in compilation,
438: the following files will be produced:
439: .(b
440: .TS
441: c c
442: l l.
443: File Contents
444:
445: Example1_defs.h scope widening macros (includes Example1.h)
446: Example1.h definitions, typedefs, and constant declarations
447: Example1_support.c routines to map between C and Courier
448: Example1_server.c server main program and support routines
449: Example1_client.c client routines to support applications calling Example
450: .TE
451: .)b
452: .pp
453: The header file
454: .i "Example1_defs.h"
455: should be included via
456: .sp
457: #include ``Example1_defs.h''
458: .sp
459: in all user-written parts of the Courier program
460: (i.e., the implementations of the client program and server procedures.)
461: .pp
462: The
463: .i "\fB-I\fIinclude-directory"
464: switch may be used on the command line of
465: .i xnscourier
466: to establish a search path for Courier specification files named in a
467: DEPENDS UPON clause. By default, the compiler looks first in the current
468: directory followed by the courier-description-file named in the
469: .i /etc/Courierservices
470: file.
471: .sh 2 "Calling Remote Procedures \- Client Implementation"
472: .pp
473: A remote procedure appears to the C programmer to look almost like
474: a local procedure (although it typically makes use of resources not
475: available on the local machine or else runs many times slower
476: than would a local procedure). A C client program (i.e. the caller
477: of a remote procedure) actually calls a stub function generated by
478: the courier compiler, which in turn executes the code necessary to
479: invoke the corresponding procedure on the remote machine.
480: .pp
481: Before calling the remote procedure it is necessary to establish a
482: Courier SPP connection (in the process binding a local socket to
483: a remote machine). This may be done by the calling the function
484: CourierOpen(), passing it as argument a structure identifying the remote
485: host. This structure
486: is of type ``ns_addr''
487: as defined in the include file
488: .i "#include <netns/ns.h>" .
489: CourierOpen() returns an anonymous pointer
490: (of type CourierConnection*) to a structure containing
491: the socket to be used for this courier call, which should be passed
492: to each remote procedure to be executed on the particular remote host.
493: CourierOpen() returns NULL if there is a problem opening an SPP connection
494: to the host specified.
495: .pp
496: For low-level access to ns_addr structures,
497: the procedure getXNSaddr() is available, taking a string in the form
498: ``network#a1.a2.a3.a4.a5.a6#socket'' (where all numbers are hex) or
499: ``networkhigh-networklow#d1-d2-d3-d4#socket'' (where all numbers are
500: 3-digit decimal numbers)
501: and returning a pointer to the
502: corresponding ns_addr structure. This result may then be passed as the
503: argument to CourierOpen().
504: More normally, the user will have a string in the form of an NS address,
505: e.g. ``jqj:computer\ science:cornell-univ''. This string can be
506: coerced into a Clearinghouse ObjectName, then used in a Clearinghouse-based
507: lookup to find the corresponding address:
508: .sp 1
509: .nf
510: Clearinghouse2_ObjectName hobj, hdefault;
511: struct ns_addr * host;
512: char * string;
513:
514: CH_NameDefault(&hdefault); /* get defaults */
515: hobj = CH_StringToName(string, &hdefault);
516: host = CH_LookupAddr(hobj, 0);
517: .fi
518: .sp 1
519: .pp
520: The SPP connection may be reused by multiple RPCs destined for the same
521: host, even if the procedures are part of different remote programs. However,
522: the SPP connection may not be reused while an RPC is outstanding; thus,
523: if you need to issue a Courier call during a BDT transfer, you will need
524: to obtain a second CourierConnection.
525: .pp
526: The client then calls the compiler-generated stub function to invoke
527: the remote procedure. This stub
528: function takes at least 2 arguments:
529: .ip (1)
530: The pointer returned from CourierOpen().
531: If the SPP connection does not
532: currently exist (i.e. has been closed by the server)
533: it is reopened for this call.
534: .ip (2)
535: A pointer to a user-supplied function which will be used if a Bulk Data
536: Transfer is required (see the section on BDT below); if this remote
537: procedure does not involve Bulk Data Transfer, then the function pointer
538: should be 0 or NULL.
539: .ip (3...)
540: One additional argument corresponding to each parameter in the Courier
541: language description of this procedure.
542: .pp
543: The remote procedure returns in one of 2 ways: either it returns
544: normally, passing back a structure corresponding to the RETURNS parameters
545: specified in the procedure description, or it signals an error which
546: may be caught using the DURING ... HANDLER mechanism described in
547: .i except(1) .
548: .pp
549: A Courier procedure is allowed to return multiple results, a language feature
550: not easily mapped into C. To provide this functionality, all UNIX
551: courier remote procedures actually return a structure
552: containing the procedure results. Thus, for a procedure named
553: Foo, declared
554: .sp 1
555: Foo: PROCEDURE [ ] RETURNS [str: STRING];
556: .sp 1
557: the C function Foo would return a structure of type FooResults, declared
558: .sp 1
559: .nf
560: typedef struct {
561: String str;
562: } FooResults;
563: .fi
564: .fi
565: .pp
566: Instead of returning a value of type determined by the RESULTS clause
567: of a PROCEDURE declaration, a Courier remote procedure call may return
568: a reject message indicating the remote system's inability to even
569: attempt a remote operation, or an abort message raising a remote error,
570: i.e. reporting the operation's failure. Reject and abort messages are
571: handled by a signalling mechanism or if uncaught cause termination of
572: the client program. For example, a client calling the remote procedure
573: defined by
574: .sp 1
575: .nf
576: NoSuchFile: ERROR = 0;
577: OtherError: ERROR [ errorstring: STRING ] = 1;
578: Example: PROCEDURE [ ] REPORTS [ NoSuchFile, OtherError ];
579: .fi
580: .sp 1
581: might be coded as
582: .sp 1
583: .nf
584: conn = CourierOpen(destaddr);
585: DURING Example(conn,NULL)
586: HANDLER switch(Exception.Code) {
587: case REJECT_ERROR:
588: fprintf(stderr,"Remote reject.\en");
589: exit(1);
590: case NoSuchFile:
591: fprintf(stderr,"No such file\en");
592: break;
593: case OtherError:
594: fprintf(stderr,"Remote error %s\en",
595: CourierErrArgs(OtherErrorArgs,errorstring) );
596: break;
597: case PROTOCOL_VIOLATION:
598: case INTERNAL_ERROR:
599: fprintf(stderr,"Local internal error %s\en",
600: Exception.Message);
601: break;
602: default:
603: fprintf(stderr,"Unknown error, type %d\en",
604: Exception.Code);
605: }
606: END_HANDLER
607: .fi
608: .sp 1
609: The error value, Exception.code, will be one of (1) ``REJECT_ERROR'',
610: which indicates a REJECT message from the remote server, (2) a program-defined
611: ERROR value (offset by ERROR_OFFSET), (3) or ``INTERNAL_ERROR''
612: or ``PROTOCOL_VIOLATION''
613: indicating
614: a serious internal error in the Unix courier implementation; in the third
615: case, a string is available as Exception.Message.
616: Both errors and rejections may have arguments, which can be accessed
617: within a handler as a struct pointed to by Exception.Message. For
618: programmer convenience a macro, CourierErrArgs, is defined, taking
619: as arguments the typedef defining the current error's arguments
620: and the name of the argument to be accessed; this macro may be used
621: only within an error handler.
622: For rejection messages, the type should be ``rejectionDetails,''
623: as defined on page 25 of the Courier spec.
624: .pp
625: When done with a particular remote connection, the client should call
626: CourierClose() with argument the pointer returned from CourierOpen()
627: to free the socket and cleanly close the connection.
628: .pp
629: The client program should be loaded with
630: .i "Example1_client.o" ,
631: .i "Example1_support.o" ,
632: and -lcourier (the XNS Courier library)
633: to produce an executable program.
634: .sh 2 "Writing a Courier Server"
635: .pp
636: The Courier protocol specifies a standard for communicating
637: parameters and results which has been adhered to in this
638: implementation.
639: It also specifies an initial connection protocol
640: and a format for messages.
641: .pp
642: There is a single Courier Daemon per UNIX machine whose function
643: is to listen on a well-known XNS port for Courier interface activation
644: requests.
645: A request contains the number of the Courier program
646: whose server is to be activated, and its version number. These two
647: numbers are used as a key in the file
648: .i /etc/Courierservices
649: to identify
650: the executable file associated with the particular courier program.
651: .i /etc/Courierservices
652: consists of a sequence of lines of the form
653: .sp 1
654: program-name program-number version courier-description-file server-binary-file
655: .sp 1
656: The daemon
657: either spawns the executable file
658: or replies with a reject message. Note that each incoming remote procedure
659: call may be serviced by a separate UNIX process.
660: This implies that connection-oriented services (services which consist of a
661: sequence of related procedure calls) must be implemented by maintaining
662: the state of connections in a file.
663: .pp
664: The executable file containing the server for a particular remote
665: program consists of a main program generated by the courier compiler
666: which interprets CALL messages from the remote client and calls
667: one or more user-written functions to implement the
668: courier procedures.
669: .pp
670: Given a courier specification for the remote program Example containing
671: remote procedure Example,
672: the server functions (including the C function Example and any support
673: routines needed)
674: should be loaded with
675: .i "Example1_server.o" ,
676: .i "Example1_support.o" ,
677: and -lcourier
678: to produce the server process that will be invoked whenever
679: an activation request arrives.
680: .pp
681: A server function receives an argument list similar to that passed by
682: a client to a remote procedure. The first two arguments in the
683: parameter list should be ignored; each succeeding argument corresponds
684: to one parameter in the courier declaration.
685: .pp
686: To return from a server function you must return a structure containing
687: the results of the procedure. If this structure contains pointers (e.g.
688: Strings) you should insure that the data pointed to is allocated
689: staticly or on the heap rather than on the stack.
690: You must not call exit(3) from within the server function; doing so will
691: cause the client (remote caller) to hang indefinitely waiting for a
692: reply.
693: .pp
694: To abort a server function, returning an error code, use the
695: ``raise(code, msg)''
696: library function, with arguments the error code and either NULL (if the
697: error takes no arguments) or a pointer to a structure containing the
698: arguments to the error. Raise causes a longjump out of the function
699: directly to the handler, and thence to the remote procedure caller.
700: For example, to return the OtherError message defined above one might code
701: .sp 1
702: .nf
703: OtherErrorArg randomerr;
704: . . .
705: randomerr.errorstring = sys_errlist[errno]);
706: raise(OtherError,(char*) &randomerr);
707: .fi
708: .sp 1
709: .pp
710: When a server function returns to its main program caller the main()
711: sends the appropriate RETURN or ABORT message to the remote client,
712: and does an exit(0). The server then holds the connection for up to 90
713: seconds waiting for another Courier call to arrive on the same SPP
714: stream.
715: .sh 2 "Dynamic Allocation"
716: .pp
717: One additional
718: .i caveat
719: is necessary when using Courier remote procedure calls from C: C does not
720: have garbage collection, so you should free any dynamically allocated storage
721: when you are done with it. In general, top level Courier objects are
722: always allocated from the stack or statically; however, strings and sequences
723: within an object are generally allocated from the heap using malloc().
724: .pp
725: A client program which calls the remote procedure Foo defined above,
726: returning a STRING,
727: actually has returned to it a C struct containing a pointer to an array
728: of malloced characters. When done with this string, the program may free
729: it by calling clear_FooResults() with argument the address of the
730: result returned by the call to Foo. Thus:
731: .sp 1
732: .nf
733: FooResults result;
734: . . .
735: result = Foo(conn,NULL);
736: . . .
737: printf("result was %s\n",result.str);
738: clear_FooResults(&result);
739: .fi
740: .sp 1
741: .sh 1 "Using Bulk Data Transfer"
742: .pp
743: .sh 2 "Overview"
744: .pp
745: When a Courier program needs to transfer an arbitrary amount of
746: information as an argument or result of a Courier procedure, the
747: procedure is usually defined to have an argument of type ``BulkData.Sink''
748: or ``BulkData.Source'' (and a ``DEPENDS UPON BulkData''
749: is included in the program).
750: The argument is a ``source'' if it is information transferred from caller
751: to server (as though a procedure argument), a ``sink'' if it is
752: information transferred from server to caller (as though a procedure
753: result). In this
754: implementation, a Courier procedure may have at most one such argument,
755: which must have the value null or immediate.
756: In a Courier call, the bulk data is transmitted in a special way,
757: multiplexed into the same data path as control messages
758: between the arguments and the results.
759: .pp
760: The BDT user should include in the
761: .i ".cr"
762: file a ``DEPENDS UPON BulkData (0) VERSION 1'', then reference these
763: arguments as BulkData.Source and BulkData.Sink in PROCEDURE
764: declarations.
765: The declaration of a Courier PROCEDURE can then indicate a bulk
766: data transfer by including in its formal argument list a variable
767: of type BulkData.Source or BulkData.Sink
768: as appropriate.
769: The corresponding parameter to the C procedure will be of type
770: BulkData1_Descriptor.
771: .sh 2 "Coding a Client"
772: .pp
773: To use Bulk Data in a client program, the Courier definition of the
774: procedure must include one BulkData.Source or BulkData.Sink parameter.
775: As the actual argument to the call, the C client passes a constant,
776: either BulkData1_immediateSource, BulkData1_immediateSink, BulkData1_nullSource,
777: or BulkData1_nullSink as appropriate. The client
778: also specifies a pointer to a user-supplied function as the second
779: argument to the remote procedure.
780: Courier sets up the transaction, then calls the supplied function with
781: one argument, the pointer returned by CourierOpen() describing the
782: SPP socket on which to write (if a source argument) or read
783: (if a sink) the bulk data.
784: .pp
785: To complete the transaction normally, the
786: function should send packets of SPP data terminated by
787: an end-of-message (if writing) or read up to but not beyond an
788: end-of-message (if reading), and should return normally to its caller.
789: To do so, it should call the procedures BDTread(), BDTwrite(), or
790: BDTclosewrite()
791: as appropriate. BDTread() and BDTwrite() take arguments analogous to read()
792: and write() except that instead of a file descriptor they accept the SPP
793: descriptor returned by CourierOpen(); their arguments are thus
794: (1) the pointer to the SPP data structure,
795: (2) a pointer to an array of characters (the IO buffer),
796: and (3) a count;
797: they return the number of characters actually read or written.
798: .pp
799: The UNIX program can finish a write transfer by calling BDTclosewrite() or
800: BDTabort(), each with the SPP descriptor as argument.
801: BDTclosewrite() produces an SPP end-of-message, while BDTabort() instructs
802: Courier to discard any buffered data and
803: send a Bulk Data Abort to abort the transaction. A read transfer may also be
804: prematurely ended by calling BDTabort().
805: .sh 2 "Coding a Server"
806: .pp
807: Writing a server that uses BDT
808: is similar to writing the BDT function in a caller.
809: The server is passed a BulkData.Source or BulkData.Sink (the two are
810: indistinguishable at run time).
811: The server routine should check to make sure that the source or sink
812: is of type null or immediate (active and passive descriptors are not
813: supported in this implementation) by means of code such as:
814: .sp 1
815: .nf
816: Foo(bdtconnection,ignoredarg,..., s, ...)
817: CourierConnection *bdtconnection;
818: BulkData1_Sink s;
819: . . .
820: switch (s.designator) {
821: case active:
822: case passive:
823: /* can't raise BulkData1_InvalidDescriptor, so */
824: raise(someerror);
825: case null:
826: /* handle null transfer */
827: break;
828: case immediate:
829: /* handle normal, i.e. immediate, transfer */
830: break;
831: }
832: .fi
833: .sp 1
834: Note that the BDT error InvalidDescriptor cannot be used unless the
835: procedure declaration explicitly notes that this is a valid REPORTS error
836: type. Normally, each courier program defines its own error to be reported
837: on BDT problems.
838: .pp
839: Use the first argument to the server procedure as the handle on the
840: BDT connection.
841: As with a client BDTabort() may
842: be used to send abort messages.
843: .sh 2 "Sending Bulk Data"
844: .pp
845: Sending bulk data, either as client or server, is quite
846: straightforward. Use the supplied procedure BDTwrite(), whose
847: semantics are similar to write(). BDTwrite() will return -1
848: if an error occurs or an abort from the listener is received; in this
849: case, the sender should immediately cease transmitting BDT data, and
850: should instead call BDTabort().
851: Typical code to send data on ``bdtconnection'',
852: in this case read from a buffered file open
853: as ``source,'' might appear as:
854: .sp 1
855: .nf
856: CourierConnection *bdtconnection;
857: FILE *source;
858: int count;
859: char buffer[SPPMAXDATA];
860: ...
861: while ( (count = fread(buffer,1,SPPMAXDATA,source)) > 0 &&
862: BDTwrite(bdtconnection,buffer,count) >= 0 )
863: ;
864: if (count <= 0) /* succsfull transfer */
865: BDTclosewrite(bdtconnection);
866: else
867: BDTabort(bdtconnection);
868: .fi
869: .sp 1
870: .pp
871: Each BDTwrite() transmits one packet after checking for an abort message
872: from the receiver.
873: A sender which gets an abort from a remote receiver must immediately
874: stop transferring data and instead must echo an abort via BDTabort()
875: to acknowledge the end of the transfer.
876: .pp
877: Also, for efficiency's
878: sake it is desirable to write packets as near as possible to the
879: nominal maximum length of an SPP packet; this suggests a buffer length of
880: 534 bytes. For programmer convenience, the file
881: .i courier.h
882: defines the symbol SPPMAXDATA as 534.
883: .sh 2 "Receiving Bulk Data"
884: .pp
885: To make receiving bulk data simple, the routine BDTread() performs checks for
886: various conditions on receipt of each packet. BDTread() will return the
887: count of the number of bytes actually read in each packet (skipping empty
888: packets), or 0 to indicate end of data. If an error or BDT abort message
889: occurs, BDTread() will return -1; if this occurs, the receiver should
890: immediately stop reading BDT data.
891: .pp
892: Typical code for receiving bulk data on the socket described by
893: ``bdtconnection'' and
894: depositing it in the file opened for buffered ouput as ``destfile''
895: might be:
896: .sp 1
897: .nf
898: CourierConnection *bdtconnection; /* BDT source descriptor */
899: FILE *destfile; /* output file */
900: char sppdata[SPPMAXDATA];
901: ...
902: count = BDTread(bdtconnection, sppdata, SPPMAXDATA);
903: while (count > 0) { /* actually read data */
904: if (fwrite(sppdata, 1, count, destfile) == 0) {
905: /* error while writing */
906: BDTabort(bdtconnection);
907: break;
908: }
909: count = BDTread(bdtconnection, sppdata, SPPMAXDATA);
910: }
911: if (count == 0) {
912: /* successful */
913: ...
914: .fi
915: .sp 1
916: .sh 2 "StreamOf declarations"
917: .pp
918: Frequently, data to be sent on a Bulk Data connection will be described
919: by a StreamOfSomething declaration in the courier specification. For
920: example, in Clearinghouse several routines are documented as returning
921: a StreamOfObjectName; unfortunately, a StreamOf declaration is recursive,
922: and so is not immediately translatable into automatic packing and unpacking
923: routines which need to know in advance how much space to allocate for the
924: result. As a kludge, we translate such types as if the recursive
925: part of the declaration were a null record.
926: Consider:
927: .sp 1
928: .nf
929: StreamOfObjectName: TYPE = CHOICE OF {
930: nextSegment (0) => RECORD [
931: segment: SEQUENCE OF ObjectName,
932: restOfStream: StreamOfObjectName ],
933: lastSegment (1) => SEQUENCE OF ObjectName};
934: .fi
935: .sp 1
936: .lp
937: In the above declaration, the ``restOfStream is effectively ignored.
938: Given this declaration, the following routine may be passed to a
939: remote procedure as the Bulk Data actor.
940: .sp 1
941: .nf
942: #include "Clearinghouse_support.c" /* get internalize_* routines */
943: #define MAXPACKS 5
944:
945: GetData(conn)
946: CourierConnection *conn;
947: {
948: int count, i;
949: Unspecified buffer[MAXWORDS*MAXPACKS], *bp, *bufend;
950: StreamOfObjectName obnames;
951:
952: bufend = buffer;
953: bp = buffer+MAXWORDS*(MAXPACKS-1); /* end of available space */
954: while (count = BDTread(conn, (char*)bufend,
955: MAXWORDS*sizeof(Unspecified))
956: ) {
957: bufend += count/sizeof(Unspecified);
958: if (bufend > bp) {
959: fprintf(stderr,"BDT read too big to fit\en");
960: BDTabort(conn);
961: /* should clear out stuff here if we knew how much */
962: }
963: }
964: bp = buffer;
965: while (bp < bufend) {
966: bp += internalize_StreamOfObjectName(&obnames,bp);
967: if (0 == (int) obnames.designator)
968: for (i = 0; i < obnames.nextSegment_case.segment.length; i++)
969: ProcessObjectName(
970: obnames.nextSegment_case.segment.sequence[i]);
971: else {
972: for (i = 0; i < obnames.lastSegment_case.length; i++)
973: ProcessObjectName(
974: obnames.lastSegment_case.sequence[i]);
975: return;
976: }
977: }
978: }
979: .fi
980: .sp 1
981: .lp
982: Note that this code is very awkward, and that it requires that the whole
983: bulk data transfer be stored in memory before it is unpacked. Stay
984: tuned; we intend to modify the compiler to make the handling of such
985: streams much easier, at the cost of incompatibility with the existing
986: scheme, of course!
987: .sh 2 "Encapsulated Protocols"
988: .pp
989: Some courier programs use what might be termed ``encapsulated protocols''
990: as a method of type punning to escape from the restrictions of the Courier
991: language. For example, in Filing
992: .sp 1
993: .nf
994: Attribute: RECORD [
995: type: AttributeType, value: SEQUENCE OF UNSPECIFIED ];
996: checksum: AttributeType = 0;
997: Checksum: TYPE = CARDINAL;
998: createdBy: AttributeType = 1;
999: CreatedBy: TYPE = User;
1000: .fi
1001: .sp 1
1002: Depending on the value of the type subfield, the data in the value field
1003: is intended to be interpreted as either a CARDINAL or a User name.
1004: .pp
1005: Such encapsulation is in general bad design unless a very compelling
1006: need for it exists. It is also awkward to support in a C program. The
1007: best way to handle such types is to write functions to code and decode
1008: the encapsulated value using the low level packing and unpacking routines
1009: provided by the Courier compiler. For example:
1010: .sp 1
1011: .nf
1012: Filing4_User
1013: AttrToUser(attr)
1014: Filing4_Attribute *attr;
1015: {
1016: Unspecified buf[2049], *bp; /* space for biggest attribute */
1017: Cardinal len;
1018: Filing4_User retval;
1019:
1020: /* useful fact: Item: TYPE = SEQUENCE OF UNSPECIFIED; */
1021: externalize_Clearinghouse2_Item(&(attr->value), buf);
1022: bp = buf;
1023: bp += internalize_Cardinal(&len, bp);
1024: bp += internalize_Filing4_User(&retval, bp);
1025: return(retval);
1026: }
1027:
1028: UserToAttr(id, attr)
1029: Filing4_User id;
1030: Filing4_Attribute *attr;
1031: {
1032: Unspecified buf[2049], *bp;
1033: Cardinal len;
1034:
1035: /* don't know length yet, so leave space for it */
1036: bp = buf + sizeof_Cardinal(len);
1037: len = externalize_Filing4_User(&id, bp);
1038: (void) externalize_Cardinal(&len, buf);
1039: internalize_Clearinghouse2_Item(&(attr->value), buf);
1040: return;
1041: }
1042:
1043: .fi
1044: .sp 1
1045: Since the SEQUENCE OF UNSPECIFIED may have undergone arbitrary
1046: transformations
1047: during deserialization, translating it to a User record consists of first
1048: reserializing it into an array of char, then deserializing it using the
1049: low-level routine appropriate to the encapsulated type. Translating to
1050: an encapsulated type is an almost precise inverse.
1051: .sh 1 "Example I: Passwd.cr"
1052: .pp
1053: This section contains a Courier program which implements remote lookup in
1054: .i "/etc/passwd"
1055: (the UNIX database of user names, passwords, home directories, and so
1056: on).
1057: It does not utilize Bulk Data Transfer, but does illustrate most other
1058: features of this courier implementation.
1059: The applications programmer would first write
1060: .i PasswordLookup.cr ,
1061: the description of the courier interface for the service, then might
1062: write
1063: .i PasswordLookup.c ,
1064: containing the routines needed to implement a server for this courier
1065: program, or might write
1066: .i lookup.c ,
1067: a typical client of this service.
1068: .bp
1069: .sh 2 "The specification (PasswordLookup.cr)"
1070: .sp 1
1071: .nf
1072: PasswordLookup : PROGRAM 754 VERSION 1 =
1073:
1074: BEGIN
1075:
1076: -- This is a translation of the passwd structure in <pwd.h>
1077:
1078: Passwd : TYPE = RECORD [
1079: pw_name, pw_passwd : STRING,
1080: pw_uid, pw_gid, pw_quota : LONG CARDINAL,
1081: pw_comment, pw_gecos, pw_dir, pw_shell : STRING
1082: ];
1083:
1084: -- Remote Errors
1085:
1086: NoSuchUser : ERROR = 0;
1087: OtherError : ERROR [ errorstring: STRING ] = 1;
1088:
1089: -- Remote entry points.
1090:
1091: LookupUid : PROCEDURE [ uid : CARDINAL ] RETURNS [ passwd : Passwd ]
1092: REPORTS [ NoSuchUser ]
1093: = 0;
1094:
1095: LookupUser : PROCEDURE [ user : STRING ]
1096: RETURNS [ passwd : Passwd, forward : STRING ]
1097: REPORTS [ NoSuchUser, OtherError ]
1098: = 1;
1099:
1100: END.
1101: .fi
1102: .sp 2
1103: .sh 2 "PasswordLookup_defs.h"
1104: .sp 1
1105: .nf
1106: /*
1107: * Declarations for Courier program PasswordLookup.
1108: */
1109: #include <courier.h>
1110: #include <except.h>
1111:
1112: typedef struct {
1113: String pw_name;
1114: String pw_passwd;
1115: LongCardinal pw_uid;
1116: LongCardinal pw_gid;
1117: LongCardinal pw_quota;
1118: String pw_comment;
1119: String pw_gecos;
1120: String pw_dir;
1121: String pw_shell;
1122: } Passwd;
1123:
1124: #define NoSuchUser 0
1125:
1126: #define OtherError 1
1127: typedef struct {
1128: String errorstring;
1129: } OtherErrorArg;
1130:
1131: typedef struct {
1132: Passwd passwd;
1133: } LookupUidResult;
1134:
1135: typedef struct {
1136: Passwd passwd;
1137: String forward;
1138: } LookupUserResult;
1139:
1140: extern LookupUidResult LookupUid();
1141:
1142: extern LookupUserResult LookupUser();
1143: .fi
1144: .sp 2
1145: .sh 2 "Makefile"
1146: .sp 1
1147: .nf
1148: CFLAGS = -O
1149: USEROBJS = lookup.o PasswordLookup_client.o
1150: SRVROBJS = PasswordLookup.o PasswordLookup_server.o
1151: LIBS = -lcr
1152: DESTDIR = /usr/lib/courier
1153:
1154: all: lookup PasswordLookup
1155:
1156: lookup: $(USEROBJS)
1157: cc -o lookup $(USEROBJS) $(LIBS)
1158:
1159: PasswordLookup: $(SRVROBJS)
1160: cc -o PasswordLookup $(SRVROBJS) $(LIBS)
1161:
1162: $(USEROBJS) $(SRVROBJS): PasswordLookup_defs.h
1163:
1164: PasswordLookup_defs.h \e
1165: PasswordLookup_server.c \e
1166: PasswordLookup_client.c: PasswordLookup.cr
1167: courier PasswordLookup.cr
1168:
1169: install: all
1170: install -s PasswordLookup $(DESTDIR)
1171:
1172: clean:
1173: -rm -f *.o PasswordLookup_*.c PasswordLookup_defs.h
1174: .fi
1175: .bp
1176: .sh 2 "The server procedures (PasswordLookup.c)"
1177: .sp 1
1178: .nf
1179: #include <stdio.h>
1180: #include "PasswordLookup_defs.h"
1181:
1182: extern Passwd *getpwnam(), *getpwuid();
1183:
1184: LookupUidResult
1185: LookupUid(CourierConnection,CourierBDTProc,uid)
1186: CourierConnection *CourierConnection, CourierBDTProc;
1187: Cardinal uid;
1188: {
1189: Passwd *pw;
1190:
1191: pw = getpwuid(uid);
1192: if (pw == NULL)
1193: raise(NoSuchUser,NULL);
1194: else {
1195: return (*(LookupUidResult*) &pw);
1196: }
1197: }
1198:
1199: LookupUserResult
1200: LookupUser(CourierConnection,CourierBDTProc,user)
1201: CourierConnection *CourierConnection, CourierBDTProc;
1202: String user;
1203: {
1204: LookupUserResult result;
1205: Passwd *pw;
1206: FILE *fwdfd;
1207: static char forward[100];
1208:
1209: pw = getpwnam(user);
1210: if (pw == NULL)
1211: raise (NoSuchUser,NULL);
1212: else {
1213: sprintf(forward,"%s/.forward",pw->pw_dir);
1214: if ((fwdfd = fopen(forward,"r")) == NULL) {
1215: forward[0] = '\e0';
1216: else {
1217: fgets(forward,100,fwdfd);
1218: fclose(fwdfd);
1219: if (strlen(forward) < 2) (
1220: static OtherErrorArg randomerr = {
1221: "invalid forwarding file"};
1222: raise(OtherError,&randomerr));
1223: }
1224: result.password = *pw;
1225: result.forward = forward;
1226: return (result);
1227: }
1228: }
1229: .fi
1230: .bp
1231: .sh 2 "The user program (lookup.c)"
1232: .sp 1
1233: .nf
1234: /*
1235: * Sample program to access remote password lookup.
1236: * Usage: lookup machine username
1237: */
1238: #include <stdio.h>
1239: #include "PasswordLookup_defs.h"
1240:
1241: main(argc, argv)
1242: int argc; char **argv;
1243: {
1244: LookupUserResult result;
1245: Passwd passwd;
1246: CourierConnection *connection;
1247:
1248: if (argc < 3 || (destaddr = getXNSaddr(argv[1])) == NULL)) {
1249: fprintf(stderr,"Usage: %s machine file ...\en",argv[0]);
1250: exit(1);
1251: }
1252: if ((connection = CourierOpen(destaddr)) == NULL) {
1253: fprintf(stderr,"Can't open connection to %s\en",argv[1]);
1254: exit(1);
1255: }
1256: DURING
1257: result = LookupUser(connection,NULL,argv[2]);
1258: HANDLER
1259: switch(Exception.Code) {
1260: case Courier_reject:
1261: fprintf("Connection rejected, code = %d\en",
1262: CourierErrArgs(rejectionDetails,designator) );
1263: exit(1);
1264: case NoSuchUser:
1265: printf("User %s unknown on %s.\en", argv[2], argv[1]);
1266: exit(0);
1267: case OtherError:
1268: fprintf(stderr,"Remote error %s\en",
1269: CourierErrArgs(OtherErrorArg,errorstring) );
1270: exit(1);
1271: }
1272: END_HANDLER;
1273:
1274: displaypwd(& result.passwd);
1275: displayfwd(result.forward);
1276: CourierClose(connection);
1277: }
1278:
1279: displaypwd(p)
1280: Passwd *p;
1281: {
1282: printf("%s:%s:%d:%d:%s:%s:%s\en",
1283: p->pw_name, p->pw_passwd, p->pw_uid, p->pw_gid,
1284: p->pw_gecos, p->pw_dir, p->pw_shell);
1285: }
1286:
1287: displayfwd(s)
1288: String s;
1289: {
1290: if (*s) printf("Mail forwarding to %s\en",s);
1291: else printf("Mail is not forwarded\en");
1292: }
1293: .fi
1294: .bp
1295: .sh 1 "Example II: PrintFile"
1296: .pp
1297: This example is a very simple application of Bulk Data Transfer.
1298: .sh 2 "PrintFile.cr"
1299: .sp 1
1300: .nf
1301: PrintFile: PROGRAM 756 VERSION 1 =
1302: BEGIN
1303:
1304: DEPENDS UPON BulkData (0) VERSION 1;
1305:
1306: -- Remote errors.
1307:
1308: CantPrint: ERROR = 0;
1309:
1310: -- Remote entry points.
1311:
1312: RPrint: PROCEDURE [ s: BulkData.Source ]
1313: REPORTS [ CantPrint ];
1314:
1315: END.
1316: .fi
1317: .sp 1
1318: .sh 2 "A typical client (remoteprint.c)"
1319: .lp
1320: .sp 1
1321: .nf
1322: /*
1323: * Sample proram to print a file remotely using trivial remote print
1324: * protocol.
1325: * Usage: remoteprint filename
1326: *
1327: */
1328: #include <stdio.h>
1329: #include <sys/types.h>
1330: #include <netns/ns.h> /* for XNS addresses */
1331: #include "PrintFile_defs.h"
1332:
1333: static FILE * source; /* communicate from main to SendSource */
1334:
1335: main(argc, argv)
1336: int argc;
1337: char *argv[];
1338: {
1339: CourierConnection *connection;
1340: struct ns_addr *destaddr;
1341:
1342: if (argc < 3 || (destaddr = getXNSaddr(argv[1])) == NULL)) {
1343: fprintf(stderr,"Usage: %s machine file ...\en",argv[0]);
1344: exit(1);
1345: }
1346: if ((connection = CourierOpen(destaddr)) == NULL) {
1347: fprintf(stderr,"Can't open connection to %s\en",argv[1]);
1348: exit(1);
1349: }
1350: argv++;
1351: while (argc-- > 2) {
1352: argv++;
1353: if (strcmp(argv[0],"-") == 0) source = stdin;
1354: else source = fopen(argv[0],"r");
1355: if (source == NULL)
1356: fprintf(stderr,"Can't open %s\en",argv[0]);
1357: else DURING
1358: RPrint(connection,SendSource,immediateSource);
1359: HANDLER
1360: fprintf(stderr,"Call to RPrint failed.\en");
1361: END_HANDLER;
1362: fclose(source);
1363: }
1364: CourierClose(connection);
1365: }
1366:
1367: SendSource(bdtconnection)
1368: CourierConnection *bdtconnection;
1369: {
1370: int count;
1371: char buffer[SPPMAXDATA];
1372:
1373: while ( (count = fread(buffer,1,SPPMAXDATA,source)) > 0 &&
1374: BDTwrite(bdtconnection,buffer,count) >= 0 )
1375: ;
1376: if (count <= 0)
1377: BDTclosewrite(bdtconnection); /* last packet with EOM set */
1378: else
1379: BDTabort(bdtconnection);
1380: }
1381: .fi
1382: .sp 2
1383: .sh 2 "Server (PrintFile.c)"
1384: .sp 1
1385: .nf
1386: #include <stdio.h>
1387: #include <sys/types.h>
1388: #include <netxns/ns.h>
1389: #include "PrintFile_defs.h"
1390:
1391: RPrintResult
1392: Rprint(source,CourierBDTProc,s)
1393: CourierConnection *source, CourierBDTProc;
1394: BulkData1_Source s;
1395: {
1396: FILE *printpipe;
1397: char sppdata[SPPMAXDATA];
1398:
1399: switch (s.designator)
1400: case active:
1401: case passive:
1402: raise(CantPrint);
1403: /*NOTREACHED*/
1404: case null:
1405: system("print /dev/null"); /* print a null file */
1406: return;
1407: case immediate:
1408: if ((printpipe = popen("print","w")) == NULL) {
1409: raise(CantPrint);
1410: /*NOTREACHED*/
1411: }
1412: count = BDTread(source, sppdata, SPPMAXDATA);
1413: while (count > 0) { /* actually read data */
1414: if (fwrite(sppdata, 1, count, printpipe) == 0) {
1415: BDTabort(source);
1416: break;
1417: }
1418: count = BDTread(source, sppdata, SPPMAXDATA);
1419: }
1420: if (pclose(printpipe) == 0 && count == 0)
1421: return;
1422: else raise(CantPrint);
1423: }
1424: .fi
1425: .sh 1 "One Final Example"
1426: .pp
1427: Finally, we present a slightly
1428: more useful example, a program to print an Interpress
1429: file on a Services-8 printer. It depends on the standard Xerox Printing
1430: specification, program 4 version 3. For an even better example, look
1431: at the printing client, xnsprint, provided with the XNS Courier distribution
1432: as
1433: .i "./examples/print/xnsprint.c" .
1434: .sp 2
1435: .nf
1436: #include <stdio.h>
1437: #include <sys/types.h>
1438: #include <netns/ns.h>
1439: #include "Printing_defs.h"
1440: #include <except.h>
1441:
1442: static FILE *ipfile = NULL;
1443:
1444: SendSource(bdtconnection)
1445: CourierConnection *bdtconnection;
1446: {
1447: int count;
1448: char buffer[SPPMAXDATA];
1449:
1450: while ( (count = fread(buffer,1,SPPMAXDATA,ipfile)) > 0 &&
1451: BDTwrite(bdtconnection,buffer,count) >= 0 )
1452: ;
1453: if (count <= 0)
1454: BDTclosewrite(bdtconnection); /* last packet with EOM set */
1455: else
1456: BDTabort(bdtconnection);
1457: }
1458:
1459: main(argc, argv)
1460: int argc;
1461: char *argv[];
1462: {
1463: PrintResults result;
1464: struct ns_addr *destaddr;
1465: CourierConnection *conn;
1466: extern struct ns_addr *getXNSaddr();
1467: PrintAttributes attributes;
1468: PrintOptions options;
1469:
1470: /* use Cornell print server, CornellS1 (slander) */
1471: destaddr = getXNSaddr("2-273#2-852-159-207");
1472: attributes.length = 0;
1473: options.length = 0;
1474: if (argc != 2 || ((ipfile = fopen(argv[1],"r")) == NULL)) {
1475: fprintf(stderr,"Usage: %s file\en",argv[0]);
1476: exit(1);
1477: }
1478: if ((conn = CourierOpen(destaddr)) == NULL) {
1479: fprintf(stderr,"Can't open connection to %s\en",xnshost);
1480: exit(1);
1481: }
1482:
1483: DURING
1484: result = Print(conn, SendSource, BulkData1_immediateSource,
1485: attributes, options);
1486: HANDLER {
1487: switch (Exception.Code) {
1488: case Busy:
1489: fprintf(stderr,"Busy\en");
1490: break;
1491: case ConnectionError:
1492: fprintf(stderr,"Connection error, %d\en",
1493: CourierErrArgs(ConnectionErrorArgs,problem));
1494: break;
1495: case InsufficientSpoolSpace:
1496: case SpoolingQueueFull:
1497: fprintf(stderr,"Insufficient spool space\en");
1498: break;
1499: case SpoolingDisabled:
1500: fprintf(stderr,"Spooling disabled\en");
1501: break;
1502: case MasterTooLarge:
1503: case TooManyClients:
1504: case ServiceUnavailable:
1505: case SystemError:
1506: case InvalidPrintParameters:
1507: case MediumUnavailable:
1508: case TransferError:
1509: fprintf(stderr,"Some Printing error, number %d\en",
1510: Exception.code-ERROR_OFFSET);
1511: break;
1512: case Undefined:
1513: fprintf(stderr,"Undefined error, number %d\en",
1514: CourierErrArgs(UndefinedArgs,problem));
1515: break;
1516: case REJECT_ERROR:
1517: fprintf(stderr,"REJECT: type = %d\en",
1518: CourierErrArgs(rejectionDetails, designator));
1519: break;
1520: default:
1521: fprintf(stderr,"Some random error, code %d\en",
1522: Exception.Code);
1523: break;
1524: }
1525: exit(1);
1526: } END_HANDLER;
1527:
1528: CourierClose(conn);
1529: printf("Done. Request ID %x %x %x %x %x\en",
1530: result.printRequestID[0], result.printRequestID[1],
1531: result.printRequestID[2], result.printRequestID[3],
1532: result.printRequestID[4]);
1533: }
1534: .fi
1535: .bp
1536: .sh 1 "Final Notes"
1537: .pp
1538: The issues of authentication and protection are
1539: difficult.
1540: They are only touched upon in this implementation.
1541: Currently, each Courier program must perform any authentication
1542: (presumably using the Authentication protocol)
1543: if this is desired. A few routines exist to allow cleints and servers
1544: to perform simple Authentication; no support for strong Authentication
1545: has yet been written.
1546: .pp
1547: This implementation is fairly inefficient, especially in
1548: the implementation of servers. Courier calls require substantial
1549: extra copying of courier arguments and results. More significantly,
1550: the requirement that each call spawn a unique process is very expensive
1551: in UNIX, and should be reconsidered.
1552: A sequence of RPCs on the same SPP stream that specifies the same program
1553: and version number uses the same process, but in all other cases a new
1554: process must be spawned for each individual RPC.
1555: .pp
1556: This implementation defines a number of reserved identifiers.
1557: .b ">>>should list them here<<<"
1558: .sh 1 "Appendix"
1559: .pp
1560: This appendix contains the grammar for the Courier language.
1561: It is similar to the YACC specification used
1562: by the Courier compiler.
1563: .sp
1564: .ps -2p
1565: .vs -2p
1566: .nf
1567: .TS
1568: l l l l l.
1569: %token identifier number string
1570: ARRAY BEGIN BOOLEAN CARDINAL
1571: CHOICE DEPENDS END ERROR
1572: FALSE INTEGER LONG OF
1573: PROCEDURE PROGRAM RECORD REPORTS
1574: RETURNS SEQUENCE STRING TRUE
1575: TYPE UNSPECIFIED UPON VERSION
1576: .TE
1577: %%
1578:
1579: Program :
1580: identifier ':' PROGRAM number VERSION number '='
1581: BEGIN DependencyList DeclarationList END '.'
1582: |
1583: identifier ':' PROGRAM '='
1584: BEGIN DependencyList DeclarationList END '.'
1585: ;
1586:
1587: DependencyList :
1588: /* empty */
1589: | DEPENDS UPON ReferencedProgramList ';'
1590: ;
1591:
1592: ReferencedProgramList :
1593: ReferencedProgram
1594: | ReferencedProgramList ',' ReferencedProgram
1595: ;
1596:
1597: ReferencedProgram :
1598: identifier '(' number ')' VERSION number
1599: ;
1600:
1601: DeclarationList :
1602: /* empty */
1603: | DeclarationList Declaration
1604: ;
1605:
1606: Declaration :
1607: identifier ':' TYPE '=' Type ';'
1608: | identifier ':' Type '=' Constant ';'
1609: ;
1610:
1611: Type :
1612: PredefinedType
1613: | ConstructedType
1614: | ReferencedType
1615: ;
1616:
1617: PredefinedType :
1618: BOOLEAN
1619: | CARDINAL
1620: | LONG CARDINAL
1621: | INTEGER
1622: | LONG INTEGER
1623: | STRING
1624: | UNSPECIFIED
1625: | LONG UNSPECIFIED
1626: ;
1627:
1628: ConstructedType :
1629: '{' CorrespondenceList '}'
1630: | ARRAY NumericValue OF Type
1631: | SEQUENCE MaximumNumber OF Type
1632: | RECORD '[' FieldList ']'
1633: | RECORD '[' ']'
1634: | CHOICE DesignatorType OF '{' CandidateList '}'
1635: | PROCEDURE ArgumentList ResultList ErrorList
1636: | ERROR ArgumentList
1637: ;
1638:
1639: ReferencedType :
1640: identifier
1641: | identifier '.' identifier
1642: ;
1643:
1644: CorrespondenceList :
1645: Correspondence
1646: | CorrespondenceList ',' Correspondence
1647: ;
1648:
1649: Correspondence :
1650: identifier '(' NumericValue ')'
1651: ;
1652:
1653: MaximumNumber :
1654: NumericValue
1655: | /* empty */
1656: ;
1657:
1658: NumericValue :
1659: number
1660: | ReferencedConstant
1661: ;
1662:
1663: DesignatorType :
1664: /* empty */
1665: | ReferencedType
1666: ;
1667:
1668: CandidateList :
1669: Candidate
1670: | CandidateList ',' Candidate
1671: ;
1672:
1673: Candidate :
1674: DesignatorList '=''>' Type
1675: ;
1676:
1677: DesignatorList :
1678: Designator
1679: | DesignatorList ',' Designator
1680: ;
1681:
1682: Designator :
1683: identifier
1684: | Correspondence
1685: ;
1686:
1687: ArgumentList :
1688: /* empty */
1689: | '[' FieldList ']'
1690: ;
1691:
1692: ResultList :
1693: /* empty */
1694: | RETURNS '[' FieldList ']'
1695: ;
1696:
1697: ErrorList :
1698: /* empty */
1699: | REPORTS '[' NameList ']'
1700: ;
1701:
1702: FieldList :
1703: Field
1704: | FieldList ',' Field
1705: ;
1706:
1707: Field :
1708: NameList ':' Type
1709: ;
1710:
1711: Constant :
1712: PredefinedConstant
1713: | ConstructedConstant
1714: | ReferencedConstant
1715: ;
1716:
1717: PredefinedConstant :
1718: TRUE
1719: | FALSE
1720: | number
1721: | '-' number
1722: | '"' string '"'
1723: ;
1724:
1725: ConstructedConstant :
1726: identifier
1727: | '[' ElementList ']'
1728: | '[' ComponentList ']'
1729: | '['']'
1730: | identifier Constant
1731: | number
1732: ;
1733:
1734: ReferencedConstant :
1735: identifier
1736: | identifier '.' identifier
1737: ;
1738:
1739: ElementList :
1740: Constant
1741: | ElementList ',' Constant
1742: ;
1743:
1744: ComponentList :
1745: Component
1746: | ComponentList ',' Component
1747: ;
1748:
1749: Component :
1750: NameList ':' Constant
1751: ;
1752:
1753: NameList :
1754: identifier
1755: | NameList ',' identifier
1756: ;
1757: .fi
1758: .vs
1759: .ps
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.