1 /****************************************************************************** 2 Copyright (c) 1992, 1995, 1996 Xerox Corporation. All rights reserved. 3 Portions of this code were written by Stephen White, aka ghond. 4 Use and copying of this software and preparation of derivative works based 5 upon this software are permitted. Any distribution of this software or 6 derivative works must comply with all applicable United States export 7 control laws. This software is made available AS IS, and Xerox Corporation 8 makes no warranty about the software, its performance or its conformity to 9 any specification. Any person obtaining a copy of this software is requested 10 to send their name and post office or electronic mail address to: 11 Pavel Curtis 12 Xerox PARC 13 3333 Coyote Hill Rd. 14 Palo Alto, CA 94304 15 Pavel@Xerox.Com 16 *****************************************************************************/ 17 18 /* This describes the complete set of procedures that a multi-user network 19 * protocol implementation must provide. 20 */ 21 22 #ifndef Net_Proto_H 23 #define Net_Proto_H 1 24 25 #include "config.h" 26 #include "options.h" 27 #include "structures.h" 28 29 struct proto { 30 unsigned pocket_size; /* Maximum number of file descriptors it might 31 * take to accept a new connection in this 32 * protocol. The generic multi-user network 33 * code will keep this many descriptors `in its 34 * pocket', ready to be freed up in order to 35 * tell potential users that there's no more 36 * room in the server. */ 37 int believe_eof; /* If true, then read() will return 0 on a 38 * connection using this protocol iff the 39 * connection really is closed. If false, then 40 * read() -> 0 will be interpreted as the 41 * connection still being open, but no data 42 * being available. */ 43 const char *eol_out_string; /* The characters to add to the end of each 44 * line of output on connections. */ 45 }; 46 47 extern const char *proto_name(void); 48 /* Returns a string naming the protocol. */ 49 50 extern const char *proto_usage_string(void); 51 /* Returns a string giving the syntax of any 52 * extra, protocol-specific command-line 53 * arguments, such as a port number. 54 */ 55 56 extern int proto_initialize(struct proto *proto, Var * desc, 57 int argc, char **argv); 58 /* ARGC and ARGV refer to just the protocol- 59 * specific command-line arguments, if any, 60 * which always come after any protocol- 61 * independent args. Returns true iff those 62 * arguments were valid. On success, all of 63 * the fields of PROTO should be filled in with 64 * values appropriate for the protocol, and 65 * *DESC should be a MOO value to pass to 66 * proto_make_listener() in order to create the 67 * server's initial listening point. 68 */ 69 70 extern enum error proto_make_listener(Var desc, int *fd, Var * canon, 71 const char **name); 72 /* DESC is the second argument in a call to the 73 * built-in MOO function `listen()'; it should 74 * be used as a specification of a new local 75 * point on which to listen for connections. 76 * If DESC is OK for this protocol and a 77 * listening point is successfully made, then 78 * *FD should be the file descriptor of the new 79 * listening point, *CANON a canonicalized 80 * version of DESC (reflecting any defaulting 81 * or aliasing), *NAME a human-readable name 82 * for the listening point, and E_NONE 83 * returned. Otherwise, an appropriate error 84 * should be returned. 85 * 86 * NOTE: It is more than okay for the server 87 * still to be refusing connections. The 88 * server's call to proto_listen() marks the 89 * time by which the server must start 90 * accepting connections. 91 */ 92 93 extern int proto_listen(int fd); 94 /* Prepare for accepting connections on the 95 * given file descriptor, returning true if 96 * successful. FD was returned by a call to 97 * proto_make_listener(). 98 */ 99 100 101 enum proto_accept_error { 102 PA_OKAY, PA_FULL, PA_OTHER 103 }; 104 105 extern enum proto_accept_error 106 proto_accept_connection(int listener_fd, 107 int *read_fd, int *write_fd, 108 const char **name); 109 /* Accept a new connection on LISTENER_FD, 110 * returning PA_OKAY if successful, PA_FULL if 111 * unsuccessful only because there aren't 112 * enough file descriptors available, and 113 * PA_OTHER for other failures (in which case a 114 * message should have been output to the 115 * server log). LISTENER_FD was returned by a 116 * call to proto_make_listener(). On 117 * successful return, *READ_FD and *WRITE_FD 118 * should be file descriptors on which input 119 * and output for the new connection can be 120 * done, and *NAME should be a human-readable 121 * string identifying this connection. 122 */ 123 124 #ifdef OUTBOUND_NETWORK 125 126 extern enum error proto_open_connection(Var arglist, 127 int *read_fd, int *write_fd, 128 const char **local_name, 129 const char **remote_name); 130 /* The given MOO arguments should be used as a 131 * specification of a remote network connection 132 * to be opened. If the arguments are OK for 133 * this protocol and the connection is success- 134 * fully made, then *READ_FD and *WRITE_FD 135 * should be set as proto_accept_connection() 136 * does, *LOCAL_NAME a human-readable string 137 * naming the local endpoint of the connection, 138 * *REMOTE_NAME a string naming the remote 139 * endpoint, and E_NONE returned. Otherwise, 140 * an appropriate error should be returned. 141 */ 142 143 #endif /* OUTBOUND_NETWORK */ 144 145 extern void proto_close_connection(int read_fd, int write_fd); 146 /* Close the given file descriptors, which were 147 * returned by proto_accept_connection(), 148 * performing whatever extra clean-ups are 149 * required by the protocol. 150 */ 151 152 extern void proto_close_listener(int fd); 153 /* Close FD, which was returned by a call to 154 * proto_make_listener(), performing whatever 155 * extra clean-ups are required by the 156 * protocol. 157 */ 158 159 #endif /* !Net_Proto_H */ 160 161 /* 162 * $Log: net_proto.h,v $ 163 * Revision 1.3 1998/12/14 13:18:34 nop 164 * Merge UNSAFE_OPTS (ref fixups); fix Log tag placement to fit CVS whims 165 * 166 * Revision 1.2 1997/03/03 04:19:07 nop 167 * GNU Indent normalization 168 * 169 * Revision 1.1.1.1 1997/03/03 03:45:04 nop 170 * LambdaMOO 1.8.0p5 171 * 172 * Revision 2.3 1996/02/08 06:16:01 pavel 173 * Updated copyright notice for 1996. Release 1.8.0beta1. 174 * 175 * Revision 2.2 1995/12/31 00:00:31 pavel 176 * Changed to support multiple listening-points. Release 1.8.0alpha4. 177 * 178 * Revision 2.1 1995/12/28 00:35:18 pavel 179 * Removed old support for protocol-specific input EOL conventions. 180 * Release 1.8.0alpha3. 181 * 182 * Revision 2.0 1995/11/30 04:53:19 pavel 183 * New baseline version, corresponding to release 1.8.0alpha1. 184 * 185 * Revision 1.6 1993/08/04 02:07:23 pavel 186 * -- Added support for the new network_listen() protocol. 187 * -- Added support for better logging of outbound connections. 188 * 189 * Revision 1.5 1992/10/23 23:03:47 pavel 190 * Added copyright notice. 191 * 192 * Revision 1.4 1992/10/21 03:02:35 pavel 193 * Converted to use new automatic configuration system. 194 * 195 * Revision 1.3 1992/10/06 18:18:04 pavel 196 * Replaced struct proto members empty_read_errno and full_write_errno by 197 * believe_eof, as part of the move of the non-blocking code from protocol 198 * implementations to net_multi.c. 199 * 200 * Revision 1.2 1992/09/26 02:24:07 pavel 201 * Added support for printing the network protocol name on server start-up. 202 * 203 * Revision 1.1 1992/09/23 17:14:17 pavel 204 * Initial RCS-controlled version. 205 */ 206