To use the library, include the file . The current release has dependencies upon Prospero in a few places: If you will not be using the Prospero pauth structure, undefine PROSPERO in ardp.h. The RREQ structure includes a reference to PAUTH by default. The ARDP library server routines currently call the Prospero function plog(). A useful future direction is to make the logging function application-specific, and inactive by default. The ardp_reply_bst() function depends upon Propero bstrings. It will not be included in the library if PROSPERO is not defined in ardp.h. --- Error handling: ARDP library functions return error codes between 1 and 20. A return value of 0 is ARDP_SUCCESS. In addition, the global variable extern int perrno; is generally set to the number of the error. (We haven't actually checked every function in the ARDP library to guarantee this). This global variable is used in the ARDP library, and in the PFS library. The function p_clear_errors() should be called from your application to clear this error indication. If you've linked with the PFS library version, then p_clear_errors() will also clear Prospero error and warning indications. This function is defined both in the PFS library and in the ARDP library; if you're a PFS library and an ARDP library user, place the PFS library version first in your link path. Its declaration is: extern void p_clear_errors(void); Printed strings associated with these errors can be found in lib/pfs/perrmesg.c. These are not currently available through the ARDP library interface, although it does not depend upon them being present. A future direction is to make these strings available through the RDP library interface. -- The ARDP library is now completely safe for sending arbitrary length-coded binary data. (Until Prospero release Alpha.5.3, this was not the case -- the server library used to append nulls to packets.) -- Notes on the PTEXT structure: The PTEXT structure has two members, ->text and ->start. On the user side, they are currently always the same; however, this is not always guaranteed to be the case in future releases of the ARDP library. ->text is used for the start of data to be parsed by the higher-level application (e.g., Prospero). The ->length member of the PTEXT structure is relative to ->start, which in this case is the same as ->text, but which is not guaranted to be so. Thus, if you need the length of the text (relative to the start of ->text), it is ->length - (->text - ->start). -- Notes on the functions: In the functions that follow, more details on the function can be found in the header preceding the function in the source code. This documentation is solely for the purpose of helping you decide which functions to look at. (Another way of saying that we are well aware that this manual is pretty sketchy.) Functions in the library that are not described here should be considered internal and should not be called by the application. The following functions are exported by the ardp library for use by the client side of a connection: ardp_abort(req) Aborts the specified request, sending an abort message to the server if currently active. If req is null, will send aborts to servers for all active requests. ardp_abort_on_int() Sets interrupt handler to abort any pending requests. ardp_pr_active() Processes new responses to active requests. If making an asynchronous request (i.e. ttwait does not equal ARDP_WAIT_TILL_TO), then this function must be called periodically, either automatically within ardp_retrieve, explicitly, or initiated by an interrupt when a response becomes available on the UDP port. ardp_retrieve(req,ttwait) Poll for, or wait for a pending request to complete. ardp_send(req,dname,dest,ttwait) Sends request to host with domain name or socket address dest, and waits ttwait microseconds for response (-1 means till timeout). ardp_set_retry(to,rt) Set retry time out (seconds) and count The following functions are exported by the ardp library for use by the server side of a connection: ardp_accept() Accepts new requests and places on appropriate queues for subsequent processing. This must be called periodically, either explicitly, or initiated by an interrupt when a request becomes available on the UDP port. ardp_bind_port(portname) Takes the name of (or #number) of a port to be opened, on which the server will listen for requests. RREQ ardp_get_nxt() Returns the next request to be processed. If none available, it will block until one is received. ardp_redirect(req,target) Sends a redirect to the client indicating the the request should be sent to a new target server identified in the second argument. ardp_respond(req,opt) Used by a server to send the current response packet once filled in. It will add the packet to the transmission queue, and send it. To indicate completion of a response, the ARDP_RESP_COMPLETE option should be specified. If the ARDP_RESP_NOSEND option is specified, the packet will be added to the transmission queue but not sent. ardp_refuse(req) Causes the specified request to be refused and notification sent to the client. ardp_reply(req,flags,message) Queues message (appending it to the req structure) and possibly sends it and other queued data to the client. Will call ardp_respond() if any completed packets can be sent (i.e., sends a partial response to speed up client/server interaction). Message is a null-terminated buffer. Can't use this interface to send binary data that might contain nulls; see ardp_reply_bst() below. ardp_rwait(req,timetowait,qpos,stime) This function is called by a server to specify a server requested time to wait for a response. This value is returned to the client which will treat it as an acknowledgment and will defer subsequent timeouts and retries until waiting the specified period. Non-zero values for qpos and stime will cause the current the specified queue position and expected system time to be provided to the client in the same message. ardp_set_queuing_policy(pf,override) Sets a function used to determine queue ordering on the server. ardp_set_prvport(fd) Sets a file descriptor that has already been opened as the input port on which the server will listen for requests. The following functions are exported by the ardp library for use by both the client and server sides of a connection: ardp_add2req(req,flags,buf,len) Adds text to a request which will subsequently be sent to the peer, and returns. RREQ ardp_rqalloc() Allocate a new request structure ardp_rqfree(req) Free a request structure ardp_rqlfree(req) Free a list of request structures PTEXT ardp_ptalloc() Allocate a new packet structure ardp_ptfree(pkt) Free a packet structure ardp_ptlfree(pkt) Free a list of packet structures /********************/ Internal functions: ardp_showbuf() is used to display buffers that might contain nulls. /******************/ Eventually to be built on top of the above: rd_sbuf Synchronously send a buffer to a destination rd_sbufa Asynchronously send a buffer to a destination rd_sync Wait until all pending requests are complete /********************/ The ARDP library respects the global integer variable pfs_debug. Levels of 9 or above cause the text of packets sent across the network to be displayed to stderr. As of Prospero Alpha.5.3 release, an ARDP library pfs_debug level of 11 or greater will cause \n and \t and \r to be printed as \n and \t and \r in the display of the contents of ARDP packets. Levels 9 and 10 cause them to be displayed as themselves. All other control characters in packets are now displayed as a \ followed by the character's octal code. (In previous releases, they were displayed as literal text, and nulls in the packet caused the display of the packet text to be ignored.) /*************/ The new ARDP_REPLY_BST() function accepts a Prospero BSTRING as its argument. This violates modularity of the ARDP library, since it requires the ARDP library to know about the bstrings layer. We need a new interface to ardp_reply() that will accept a length-coded buffer, and then a wrapper around it in the pfs library that will accept the bstring. Future directions for this function are noted at ISI in /nfs/pfs/notes/ardp-directions. ardp_reply_bst(RREQ req, /* Request to which this is a response */ int flags, /* Whether this is the final message */ char *message) /* The data to be sent. Must be a bstring. */ /**** BUGS & future directions *****/ ardp_retrieve() and ardp_send() both call p_clear_errors() internally. This is inconsistent with the behavior of the rest of the ARDP library and of most of the PFs library, which do not clear error indications themselves. Look over ardp.h. -Make it independent of Prospero directory service: Put authentication stuff into ardp.h as a formal library. Alternatively, make the directory service use the 'app' optional member. (at least until the authentication stuff is better defined). Make sure the app optional member is defined and explained in the ARDP stuff. -Get rid of #define PROSPERO in ardp.h -ARDP_DEFAULT_PEER and ARDP_DEFAULT_PORT must become optional constants. Change the ardp library interface so that the logging function is specified at runtime initialization. ardp_reply should have the interface changed to accept a message length, just like ardp_add2req() does. Ditto any other functions in the libardp interface that expect just null terminated buffers. The ARDP library should be better documented for potential programmers. Fix bug: ardp_respond() expects trailing null on buffer ardp_add2req() hands. (this is on the SWA todo list as a separate item). SWA has rewritten ardp_add2req on paper; need to type in these simplifying changes.