make-rpc-client

Arguments: port-class &key home remote-host remote-port poll-interval poll-count if-error re-connect begin open verbose debug mode export message-tiemout server message-length ssl passcode confirm

make-rpc-client is the new name for the function named define-rpc-client in releases prior to 6.2. The new name follows standard Common Lisp naming conventions, since this function creates a server object.

This function creates an rpc-port instance appropriate for the specified port-class ready to connect to an advertising host. The value returned is the rpc-port instance if the operation succeeds, or nil and a second value that describes the cause of the failure if the operation fails.

When the port-class argument is a subtype of rpc-socket-port, then an instance of a stream socket client is created. Note that in this case, no value should be specified for the server keyword argument, which is used for datagram socket clients only. When port-class is also a subclass of with-rpc-port-enabler (such as rpc-socket-port-with-enabler), a passcode keyword argument is also accepted. It is described with the other keyword arguments below.

When the port-class argument is a subtype of rpc-datagram-port, then an instance of a datagram socket client is created. Note that in this case, no value should be specified for the home keyword argument, since the home name of a datagram connection is constructed from the local and remote hosts and ports. The server keyword argument can be a rpc-datagram-server instance or the name of one. The server instance is used for incoming messages and the client instance is used for outgoing messages.

The actual connection happens when rpc-open-client is called. If the open argument is non-nil, an implicit call to rpc-open-client is made.

The port-class argument may be nil to denote the default port class, rpc-socket-port.

The keyword arguments are generally similar to those of make-rpc-server. They are:

• home: same as for make-rpc-server.
• remote-host: a string naming the host where the server is listening. The default is "localhost".
• remote-port: a required number, the port number of the port at which the server is listening.
• poll-interval: the number of seconds to wait between attempts to connect.
• poll-count: nil or a number. When nil, try only once; when a number, try that many times.
• if-error: same as for make-rpc-server.
• re-connect: nil (allow only one explicit connection); :on-first-use or :first-use (allow only one implicit connection); :on-demand, :demand (re-connect when necessary) or :connect (attempt to re-connect and if the re-connect fails, tries a new connect).
• begin: same as for make-rpc-server.
• open: when non-nil, call rpc-open-client.
• verbose: same as for make-rpc-server.
• debug: same as for make-rpc-server.
• mode: same as for make-rpc-server.
• export: a list of pairs passed to export-remote-symbol when a connection is established.
• message-timeout: when the port-class argument is a subtype of rpc-datagram-port, same as for make-rpc-server. This argument is ignored when the port-class argument is a subtype of rpc-socket-port.
• message-length: when the port-class argument is a subtype of rpc-datagram-port, same as for make-rpc-server. This argument is ignored when the port-class argument is a subtype of rpc-socket-port.
• server: this argument is used only when port-class is a subclass of rpc-datagram-port. The value may be nil, the name of an rpc-datagram-server instance or an rpc-datagram-server instance. If nil, the host and port arguments must be sufficient to create an rpc-datagram-server instance.
• ssl: this argument is used only when port-class is a subclass of rpc-socket-port. When non-nil, call make-ssl-client-stream immediately after connecting to a server
• passcode (this argument is only used when port-class is a subclass of with-rpc-port-enabler, for example, when it is an instance of rpc-socket-port-with-enabler): the passcode argument sent in an implicit :enable-client request that is sent after a connection is established.
• confirm: when this argument is non-nil, the Lisp RPC protocol includes additional confirmation messages that track the progress of a remote call in more detail (see rpc-query for more details). The default value is nil.

  A non-nil value may be applicable when using a very slow network connection. In such cases more detailed progress information could be useful.

  This argument was not available in releases prior to 6.2, where this function worked as if this argument was specified non-nil.

See also rpc.htm for general information on the Remote Procedure Call utility in Allegro CL.

Copyright (c) 1998-2008, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.0. The object described on this page has been modified in the 8.0 release; see the Release Notes.
Created 2007.4.30.