TCPIP Services, Programming Interfaces, RPC Server Routines
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help TCPIP Services, Programming Interfaces, RPC Server Routines *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Server routines allow C programs to receive procedure calls from
client programs over the network.
| 1 - registerrpc |
Obtains a unique systemwide procedure identification number.
Format
#include <rpc/rpc.h>
int registerrpc(u_long prognum, u_long versnum, u_long
procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t
outproc );
1.1 - Arguments
prognum
The program number associated with the service procedure.
versnum
The version number associated with the service procedure.
procnum
The procedure number associated with the service procedure.
progname
The address of the service procedure being registered with the
ONC RPC service package.
inproc
The XDR routine used to decode the service procedure's arguments.
outproc
The XDR routine used to encode the service procedure's results.
1.2 - Description
The registerrpc routine performs the following tasks for a
server:
o Creates a UDP server handle. See the svcudp_create routine for
restrictions.
o Calls the svc_register routine to register the program with
the Portmapper.
o Adds prognum, versnum, and procnum to an internal list of
registered procedures. When the server receives a request, it
uses this list to determine which routine to call.
A server should call registerrpc for every procedure it
implements, except for the NULL procedure. If a request arrives
for program prognum, version versnum, and procedure procnum,
progname is called with a pointer to its parameters.
1.3 - Return Values
0 Indicates success.
-1 Indicates failure.
| 2 - seterr_reply |
Fills in the error text in a reply message.
Format
#include <rpc/rpc.h>
void seterr_reply(struct rpc_msg *msg, struct rpc_err *error);
2.1 - Arguments
msg
A pointer to a reply message buffer.
error
A pointer to an rpc_err structure containing the error associated
with the reply message.
2.2 - Description
Given a reply message, seterr_reply fills in the error field.
2.3 - Return Values
None
| 3 - svc_destroy |
A macro that frees the memory associated with an RPC server
handle.
Format
#include <rpc/rpc.h>
void svc_destroy(SVCXPRT *xprt);
3.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
3.2 - Description
The svc_destroy routine returns all the private data structures
associated with a server handle. If the server handle creation
routine received the value RPC_ANYSOCK as the socket, svc_destroy
closes the socket. Otherwise, your program must close the socket.
3.3 - Return Values
None
| 4 - svc_freeargs |
A macro that frees the memory allocated when the procedure's
arguments were decoded.
Format
#include <rpc/rpc.h>
bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char
*in);
4.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
inproc
The XDR routine used to decode the service procedure's arguments.
in
A pointer to the service procedure's decoded arguments.
4.2 - Description
The svc_destroy routine returns the memory that the svc_getargs
routine allocated to hold the service procedure's decoded
arguments. This routine calls the xdr_free routine.
4.3 - Return Values
TRUE Success; memory successfully deallocated.
FALSE Failure; memory not deallocated.
| 5 - svc_getargs |
A macro that decodes the service procedure's arguments.
Format
#include <rpc/rpc.h>
bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
5.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
inproc
The XDR routine used to decode the service procedure's arguments.
in
A pointer to the service procedure's decoded arguments.
5.2 - Description
This routine calls the specified XDR routine to decode the
arguments passed to the service procedure.
5.3 - Return Values
TRUE Successfully decoded.
FALSE Decoding unsuccessful.
| 6 - svc_getcaller |
A macro that returns the address of the client that called the
service procedure.
Format
#include <rpc/rpc.h>
struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
6.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
6.2 - Description
This routine returns a sockaddr_in structure containing the
internet address of the RPC client routine that called the
service procedure.
6.3 - Return Values
struct sockaddr_ A pointer to the socket descriptor.
in
| 7 - svc_getreqset |
Returns data for each server connection.
Format
#include <rpc/rpc.h>
void svc_getreqset(fd_set *rdfds);
7.1 - Arguments
rdfds
A pointer to the read file descriptor bit mask modified by the
select routine.
7.2 - Description
The svc_getreqset routine is for servers that implement custom
asynchronous event processing or that do not use the svc_run
routine. You may only use svc_fdset when the server does not use
svc_run.
You are unlikely to call this routine directly, because the
svc_run routine calls it. However, there are times when you
cannot call svc_run. For example, suppose a program services
RPC requests and reads or writes to another socket at the same
time. The program cannot call svc_run. It must call select and
svc_getreqset.
The server calls svc_getreqset when a call to the select
system call determines the server has received one or more RPC
requests. The svc_getreqset routine reads in data for each server
connection, then calls the server program to handle the data.
The svc_getreqset routine does not return a value. It finishes
executing after all sockets associated with the variable rdfds
have been serviced.
You may use the global variable svc_fdset with svc_getreqset. The
svc_fdset variable is the RPC server's read file descriptor bit
mask.
To use svc_fdset:
1. Copy the global variable svc_fdset into a temporary variable.
2. Pass the temporary variable to the select routine. The select
routine overwrites the variable and returns it.
3. Pass the temporary variable to the svc_getreqset routine.
7.3 - Example
#define MAXSOCK 10
int readfds[ MAXSOCK+1], /* sockets to select from*/
i, j;
for(i = 0, j = 0; i << MAXSOCK; i++)
if((svc_fdset[i].sockname != 0) && (svc_
fdset[i].sockname != -1))
readfds[j++] = svc_fdset[i].sockname;
readfds[j] = 0; /* list of sockets ends with a zero */
switch(select(0, readfds, 0, 0, 0))
{
case -1: /* an error happened */
case 0: /* time out */
break;
default: /* 1 or more sockets ready for reading */
errno = 0;
svc_getreqset(readfds);
if( errno == ENETDOWN || errno == ENOTCONN)
sys$exit( SS$_THIRDPARTY);
}
7.4 - Return Values
None
| 8 - svc_register |
Registers the server program with the Portmapper service.
Format
#include <rpc/rpc.h>
bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long
versnum, void (*dispatch)(), u_long protocol);
8.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
dispatch
The address of the service dispatch procedure that the server
procedure calls. The procedure dispatch has the following form:
void dispatch(request, xprt)
struct svc_req *request;
SVCXPRT *xprt;
The svc_run and svc_getreqset call the dispatch routine.
protocol
The protocol that the server procedure uses. Values for this
parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is
zero, the service is not registered with the Portmapper service.
8.2 - Description
Associates prognum and versnum with the service dispatch
procedure dispatch. If protocol is non-zero, then a mapping of
the triple [prognum, versnum, protocol] to xprt->xp_port is also
established with the local Portmapper service.
8.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
| 9 - svc_run |
Waits for incoming RPC requests and calls the svc_getreqset
routine to dispatch to the appropriate RPC server program.
Format
#include <rpc/rpc.h>
void svc_run();
9.1 - Arguments
None
9.2 - Description
The svc_run routine calls the select routine to wait for RPC
requests. When a request arrives, svc_run calls the svc_getreqset
routine. Then svc_run calls the select routine again.
The svc_run routine never returns.
You may use the global variable svc_fdset with the svc_run
routine. See the svc_getreqset routine for more information on
svc_fdset.
9.3 - Return Values
Never returns
| 10 - svc_sendreply |
Sends the results of a remote procedure call to an RPC client.
Format
#include <rpc/rpc.h>
bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char
*out);
10.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
outproc
The XDR routine used to encode the server procedure's results.
out
A pointer to the server procedure's results.
10.2 - Description
Called by an ONC RPC service's dispatch routine to send the
results of a remote procedure call.
10.3 - Return Values
TRUE Indicates success.
FALSE Indicates failure.
| 11 - svc_unregister |
Calls the Portmapper to unregister the specified program and
version for all protocols. The program and version are removed
from the list of active servers.
Format
#include <rpc/rpc.h>
void svc_unregister(u_long prognum, u_long versnum);
11.1 - Arguments
prognum
The program number associated with the server procedure.
versnum
The version number associated with the server procedure.
11.2 - Description
Removes all mapping of the double [prognum, versnum] to dispatch
routines, and of the triple [prognum, versnum, *] to port number.
11.3 - Return Values
None
| 12 - svcerr_auth |
Sends an authentication error to the client.
Format
#include <rpc/rpc.h>
void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);
12.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
why
The reason for the authentication error.
12.2 - Description
Called by a service dispatch routine that refuses to perform a
remote procedure call due to an authentication error.
12.3 - Return Values
None
| 13 - svcerr_decode |
Sends an error code to the client indicating that the server
procedure cannot decode the client's arguments.
Format
#include <rpc/rpc.h>
void svcerr_decode(SVCXPRT *xprt);
13.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
13.2 - Description
Called by a service dispatch routine that cannot successfully
decode its parameters. See also the svc_getargs routine.
13.3 - Return Values
None
| 14 - svcerr_noproc |
Sends an error code to the client indicating that the server
program does not implement the requested procedure.
Format
#include <rpc/rpc.h>
void svcerr_noproc(SVCXPRT *xprt);
14.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
14.2 - Description
Called by a service dispatch routine that does not implement the
procedure number that the client requested.
14.3 - Return Values
None
| 15 - svcerr_noprog |
Sends an error code to the client indicating that the server
program is not registered with the Portmapper.
Format
#include <rpc/rpc.h>
void svcerr_noprog(SVCXPRT *xprt);
15.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
15.2 - Description
Called when the desired program is not registered with the ONC
RPC package. Generally, the Portmapper informs the client when a
server is not registered. Therefore, service implementors usually
do not use this routine.
15.3 - Return Values
None
| 16 - svcerr_progvers |
Sends an error code to the client indicating that the requested
program is registered with the Portmapper but the requested
version of the program is not registered.
Format
#include <rpc/rpc.h>
void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long
high_vers);
16.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
low_vers
The lowest version of the requested program that the server
supports.
high_vers
The highest version of the requested program that the server
supports.
16.2 - Description
Called when the desired version of a program is not registered
with the ONC RPC package. Generally, the Portmapper informs
the client when a requested program version is not registered.
Therefore, service implementors usually do not use this routine.
16.3 - Return Values
None
| 17 - svcerr_systemerr |
Sends an error code to the client indicating that the an error
occurred that is not handled by the protocol being used.
Format
#include <rpc/rpc.h>
void svcerr_systemerr(SVCXPRT *xprt);
17.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
17.2 - Description
Called by a service dispatch routine when it detects a system
error not covered by any particular protocol. For example, if a
service can no longer allocate storage, it may call this routine.
17.3 - Return Values
None
| 18 - svcerr_weakauth |
Sends an error code to the client indicating that an
authentication error occurred. The authentication information
was correct but was insufficient.
Format
#include <rpc/rpc.h>
void svcerr_weakauth(SVCXPRT *xprt);
18.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
18.2 - Description
Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient (but correct)
authentication parameters. The routine calls svcerr_auth (xprt,
AUTH_TOOWEAK).
18.3 - Return Values
None
| 19 - svcraw_create |
Creates a server handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
SVCXPRT *svcraw_create();
19.1 - Arguments
None
19.2 - Description
Creates a in-program ONC RPC service transport, to which it
returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding client should live
in the same address space; see the clntraw_create routine. The
svcraw_create and clntraw_create routines allow simulation and
acquisition of ONC RPC overheads (such as round-trip times),
without any kernel interference.
19.3 - Return Values
SVCXPRT * A pointer to an RPC server handle for the
in-memory transport.
NULL Indicates failure.
| 20 - svcfd_create |
Creates an RPC server handle using the specified open file
descriptor.
Format
#include <rpc/rpc.h>
SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize);
20.1 - Arguments
fd
The number of an open file descriptor.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.
20.2 - Description
Creates an RPC server handle using the specified TCP socket, to
which it returns a pointer. The server should call the svcfd_
create routine after it accepts an incoming TCP connection.
20.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
| 21 - svctcp_create |
Creates an ONC RPC server handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int
recvsize);
21.1 - Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
If the socket is not bound to a local TCP port, then this routine
binds it to an arbitrary port.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.
21.2 - Description
Creates an RPC server handle using the TCP/IP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
21.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
| 22 - svcudp_bufcreate |
Creates an ONC RPC server handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int
recvsize);
22.1 - Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
sendsize
The size of the send buffer. If you specify 0, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify 0, the routine
chooses a suitable default.
22.2 - Description
Creates an RPC server handle using the UDP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
22.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
| 23 - svcudp_create |
Creates an ONC RPC server handle for a non-buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
SVCXPRT *svcudp_create(int sock);
23.1 - Arguments
sock
The socket with which the connection is associated. If sock is
RPC_ANYSOCK, then this routine opens a new socket and sets sock.
23.2 - Description
Creates an RPC server handle using the UDP transport, to
which it returns a pointer. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and xprt->xp_port is the
transport's port number. The service is automatically registered
as a transporter (thereby including its socket in svc_fds such
that its socket descriptor is included in all RPC select system
calls).
NOTE
Since UDP/IP-based ONC RPC messages can only hold up to 8
Kbytes of encoded data, this transport cannot be used for
procedures that take large arguments or return huge results.
23.3 - Return Values
SVCXPRT * A pointer to the server handle.
NULL Indicates failure.
| 24 - xprt_register |
Adds a socket associated with an RPC server handle to the list of
registered sockets.
Format
#include <rpc/rpc.h>
void xprt_register(SVCXPRT *xprt);
24.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
24.2 - Description
Activation of a transport handle involves setting the most
appropriate bit for the socket associated with xprt in the svc_
fds mask. When svc_run() is invoked, activity on the transport
handle is eligible to be processed by the server.
The svc_register routine calls this routine; therefore, you are
unlikely to use this routine directly.
24.3 - Return Values
None
| 25 - xprt_unregister |
Removes a socket associated with an RPC server handle from the
list of registered sockets.
Format
#include <rpc/rpc.h>
void xprt_unregister(SVCXPRT *xprt);
25.1 - Arguments
xprt
A pointer to an RPC server handle created by any of the server
handle creation routines.
25.2 - Description
Removes the socket associated with the indicated handle from the
list of registered sockets maintained in the svc_fdset variable.
Activity on the socket associated with xprt will no longer be
checked by the svc_run routine.
The svc_unregister routine calls this routine; therefore, you are
unlikely to use this routine directly.
25.3 - Return Values
None
| 26 - _authenticate |
Authenticates the request message.
Format
#include <rpc/rpc.h>
enum auth_stat _authenticate(struct svc_req *rqst, struct
rpc_msg *msg);
26.1 - Arguments
rqst
A pointer to an svc_req structure with the requested program
number, procedure number, version number, and credentials passed
by the client.
msg
A pointer to an rpc_msg structure with members that make up the
RPC message.
26.2 - Description
Returns AUTH_OK if the message is authenticated successfully. If
it returns AUTH_OK, the routine also does the following:
o Sets rqst->rq_xprt->verf to the appropriate response verifier.
o Sets rqst->rq_client_cred to the "cooked" form of the
credentials.
The expression rqst->rq_xprt->verf must be preallocated, and its
length set appropriately.
The program still owns and is responsible for msg->u.cmb.cred and
msg->u.cmb.verf. The authentication system retains ownership of
rqst->rq_client_cred, the "cooked" credentials.
26.3 - Return Values
enum auth_stat The return status code for the authentication
checks:
AUTH_OK=0-Authentication checks successful.
AUTH_BADCRED=1-Invalid credentials (seal
broken)
AUTH_REJECTEDCRED=2-Client should begin new
session
AUTH_BADVERF=3-Invalid verifier (seal
broken)
AUTH_REJECTEDVERF=4-Verifier expired or was
replayed
AUTH_TOOWEAK=5-Rejected due to security
reasons
AUTH_INVALIDRESP=6-Invalid response
verifier
AUTH_FAILED=7-some unknown reason
|
|
