############################################################################## # # Copyright (c) 1998 by # blaxxun interactive Inc, San Francisco, California, USA # All rights reserved # # MODULE NAME: $RCSfile: raextern.txt,v $ # REVISION: $Revision: 1.9 $ # DATE: $Date: 2001/02/16 12:36:00 $ # AUTHOR: $Author: peter $ # STATE: $State: Exp $ # # PROJECT: blaxxun # SYSTEM: server - blaxxun server processes - Community Server # SUBSYSTEM: doc - documentation of Remote Access Server # ############################################################################## # # Description of external interface of Remote Access Server.Table of Contents:
The remote access server allows to send a string array from a
remote access client to the remote access server.
Those strings can then be processed and a string array of results
can be sent back to the client.
Example applications that can be implemented based on the RA server are:
- A database server, that maintains a remote database, database queries
can be sent remotely to the server and query results can be sent
back to the client.
1.2. General Notes on Remote Database Access.
contents
There are blocking client API calls to the RA server and non blocking
ones to be used in server applications.
The blocking client API calls will only return
if either an error occurs or the RA server sends a positive reply.
If an error occurs the client database request has been executed by the
server at most once, i.e either 0 or 1 times.
If no error occurs the client database request has been executed by the
server exactly once, i.e. exactly one time.
In order for remote database access to work correctly with this scheme
it is necessarry that all remote database access calls are idempotent,
i.e. yield the same result if executed more than once.
All read operations are idempotent. But close care has to be taken
with write operations in order to make them idempotent.
E.g: "Set the value of the score of the user to 37" is idempotent.
"Increase the value of the score of the user by one" is NOT!!!!.
2. Files
contents
2.1. libra.a - UNIX library
contents
For UNIX systems
this library is distributed in directory src/linuxbin
and src/solarisbin.
In the cdserver distribution the functions of this library are actually included
in the library libchapi.a.
The library contains the application interface. It is actually a blaxxun process
that has to be linked with the file raevent.o, libconfig.a libpaa.a,
libpacket.a and libproc.a.
The library also contains the client interface calls for the RA server.
The interface to the process is as follows:
------------------------------------------------------------------------------
FUNCTION NAME: main raserver
DESCRIPTION:
Does the work of the RA server.
The option -TRACE enables traces to the logfile.
This option can be toggled sending a kill -SIGUSR2 to the process.
The option -D prevents the process from disconnecting from the
control terminal for debug purposes.
If the process receives a kill -SIGUSR1 it writes it complete
status information to the log file.
IMPLICIT INPUTS:
The environment variable $BSIROOT has to be set.
The process assumes existence of the directories
$BSIROOT/log and $BSIROOT/status.
IMPLICIT OUTPUTS:
Writes logs to the file $BSIROOT/log/raserver.<portnumberused>
RETURN VALUES:
The process can be terminated by kill -SIGTERM
exit( 0 ); OK
exit( 1 ); an error occured
DESIGN LANGUAGE:
None
------------------------------------------------------------------------------
*/
int main( int argc, char * argv[] )
{
static char usage[] =
"Usage: %s -p port -tp tcpport -ta tcpaddress [ -TRACE -D ]\n\
where\n\
-p port: is the port the RA server should work with\n\
-tp tcpport: is the tcp port the RA server should work with\n\
-ta tcpaddr: is the tcp ip address the RA server should work with\n\
-TRACE: enables the trace flag\n\
-D: is for debugging\n";
In order to use this process install Community Server 3.00, create the
raserver in src, copy it to the
Community Server <installdir>/bin directory
and add it to the file <installdir>/chstart.
For NT systems all binary files are distributed in directory src/ntbin
along with a MS VC++ 4.2 makefile.
1. Edit file rantserv.h
- insert your own names for the both defines:
#define RANT_SERVICE_NAME "raserver"
// this is the name of your NT service and also the registry
// prefix for the "apserverPort" reg value.
Edit the file raevent.c
- modify the existing event handler functions to your needs.
2. Open the makefile raserver.mak in VC++ 4.2.
Usage: sinstall.exe servicename servicedisplayname exepath
5. Enter a new value in the registry:
- Open regedit.exe6. Start the NT Service Control Manager and start your new service. The new process writes a log file under <installdir>\log\
- Go to key HKEY_LOCAL_MACHINE/Software/blaxxunInteractive/Community Server
- Add a new String value "raserverPort" = 2070 (use the servicename you entered in the H-FILE for APNT_SERVICE_NAME as prefix, and choose an available UDP port)
This include file gets distributed in directory src.
File raextern.h
PROJECT: VWP - blaxxun virtual worlds platform
SYSTEM: server - server processes
COMPONENT: apserver - Community Server API server
DESCRIPTION:
external include file of ra server
This file resides in the directory src.
File raevent.c
PROJECT: VWP - blaxxun virtual worlds platform
SYSTEM: server - server processes
COMPONENT: apserver - Community Server API server
DESCRIPTION:
Event functions called. The functions given in this file are
examples for the Event Functions of the Interface.
Customize them to your own needs.
3.1. Makros and Constants
contents
*/ /* * defaults for timeout and retries */ #define RA_DEFAULT_RETRIES 5 #define RA_DEFAULT_TIMEOUT 3 /* * maximum number of arguments for call */ #define RA_MAX_N_ARGUMENTS 1500 #define RA_MAX_SIZE_ARGUMENTS 32000 /* * in the http request case we allow the following request size */ #define RA_MAX_HTTP_REQUEST_SIZE ( 256 * 1024 ) /* * Error codes for the ra client calls */ #define RA_ERR_HOSTNAME -1 /* error during hostname lookup */ #define RA_ERR_SOCKET -2 /* error during socket creation */ #define RA_ERR_KILLED -3 /* sigterm received */ #define RA_ERR_CONNECT -4 /* error during connect to the raserver */ #define RA_ERR_ARGSIZE -5 /* length of arguments exceeds limit */ #define RA_ERR_INARGC -6 /* Parameter inargc exceeds maximum value */ #define RA_ERR_TIMEOUT -7 /* The raserver did not answer */ #define RA_ERR_MEMORY -8 /* Client is out of memory */ #define RA_ERR_CLIENT -9 /* Invalid client pointer */ #define RA_ERR_DENIED -10 /* Server denied request */ #define RA_ERR_DELETED -11 /* a udp client delete call has been made */ #define RA_ERR_NORESULT -12 /* the server didn't give a result */ #define RA_ERR_WRONGRESULT -13 /* the server didn't give correct result */
*/
typedef unsigned long ra_ip_t;
typedef unsigned short ra_port_t;
typedef unsigned long ra_4byte_t;
/*
* A pointer to the Remote Acess UDP Request handler function
*/
typedef void (* raHandlerReplyPtr_t)( char * request, void * userdata, int rc );
typedef void (* raHandlerUdpFuncPtr_t)( char * client, int argc, char *argv[] );
typedef void (* raHandlerHttpFuncPtr_t)( char * client );
typedef void (* raHandlerShutdownPtr_t)( int exitcode );
typedef void (* raHandlerPeriodicPtr_t)( struct timeval * now );
/*
* The following type is used internally by the RA server
*/
typedef struct raserver_s
{
time_t now; /* the current time set by id_reply */
time_t lastlog; /* last time log was printed */
ra_port_t port; /* port number used by RA server */
ra_ip_t ip; /* ip address used by server */
int socket; /* udp socket used by RA server */
int standalone; /* flag: this is real raserver */
struct timeval period; /* period RA server works with */
struct timeval iperiod; /* internal period of RA server */
struct timeval nextperiod; /* next time periodic event is called */
volatile int statusprint; /* flag for status print, set by */
/* id_sigusr1_handler */
/* number of packets received of type */
ra_4byte_t n0packets; /* length 0 */
ra_4byte_t nunknown; /* unknown packets */
ra_4byte_t nudprequest; /* UDP client requests */
ra_4byte_t nreplays; /* UDP client requests replays */
char *sessions; /* pointer to sessions hash table */
ra_4byte_t nsessions; /* number of active udp sessions */
ra_4byte_t tsessions; /* total number of udp sessions ever */
void * sessionhead; /* head and tail of list of udp */
void * sessiontail; /* sessions */
void * connhead; /* head and tail of list of tcp */
void * conntail; /* connections */
ra_4byte_t nconnections; /* number of active tcp connections */
ra_4byte_t tconnections; /* total number of tcp connections */
void * clienthead; /* head and tail of list of clients */
void * clienttail;
/* the handlers for remote access requests */
raHandlerUdpFuncPtr_t ra_handler;
raHandlerHttpFuncPtr_t ra_httphandler;
raHandlerShutdownPtr_t ra_shutdown;
raHandlerPeriodicPtr_t ra_periodic;
int tcpsocket; /* tcp listen socket used */
ra_port_t tcpport; /* port number used by RA server */
char * tcpHostname; /* on multihomed firewall machines */
ra_ip_t tcpip; /* the tcp and the udp connections */
/* can happen on different IP addrs */
/* In this case the tcp hostname has */
/* to be specified through the */
/* commandline, the udp address is */
/* taken from the server configuration*/
} raserver_t;
Event Functions are called by the Community Server RA without
a need to register them.
Examples for the functions are supplied in raevent.c. Those functions
may be customized by users of the RA server.
4.1. raEventStartup
contents
------------------------------------------------------------------------------
FUNCTION NAME: raEventStartup
DESCRIPTION:
This function is called when the RA server is started.
NOTE: In order to make the process run correctly on NT this function must
not perform any exits, use a return code of 110 or higher as the
example does.
RESTRICTION:
In case the remote access library is linked into an apserver,
this function is NOT called. The API server only calls its
own startup event chEventStartup.
RETURN VALUES:
int rc == 0: ok process started successfully
rc != 0: the startup failed, the process will go down with
the exitcode returned
------------------------------------------------------------------------------
*/
int raEventStartup(
int argc, /* number of parameters */
char *argv[] /* comamnd line parameters */
)
------------------------------------------------------------------------------
FUNCTION NAME: raEventShutdown
DESCRIPTION:
This function is called when the RA server is terminated.
RESTRICTION:
In case the remote access library is linked into an apserver,
this function is NOT called. The API server only calls its
own shutdown event chEventShutdown.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raEventShutdown(
int exitcode /* return code for exit call */
)
------------------------------------------------------------------------------
FUNCTION NAME: raEventPeriodic
DESCRIPTION:
This function is called periodically.
The default is every 60 seconds, the default can be changed by
calling raSetPeriod.
The minimum value possible for period is 100000 microseconds.
RESTRICTION:
In case the remote access library is linked into an apserver,
this function is NOT called. The API server only calls its
own periodic event chEventPeriodic.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raEventPeriodic(
struct timeval * now /* time when function was called */
)
------------------------------------------------------------------------------
FUNCTION NAME: raEventUdpRequest
DESCRIPTION:
This function is called whenever a UDP client request comes in.
Use the server api call raGetArg to retrieve the arguments one by
one.
And use raSetResult to set result strings for the client application.
At least one result string has to be set, otherwise the client api
call returns with the error RA_ERR_DENIED.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raEventUdpRequest(
char *client, /* client that sent the request */
int inargc, /* number of arguments sent */
char *inargv[] /* pointerarray of arguments sent */
)
------------------------------------------------------------------------------
FUNCTION NAME: raEventHttpRequest
DESCRIPTION:
This function is called whenever a Http client request comes in.
And use raSetHttpResult to set result strings for the client application.
At least one result string has to be set, otherwise the client api
call returns with the error RA_ERR_DENIED.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raEventHttpRequest(
char *connection /* r: connection that sent the request */
)
Not yet implemented.
5. General RA API Calls
contents
The following general API Calls exist.
5.1. raGetServerIp
contents
------------------------------------------------------------------------------
FUNCTION NAME: raGetServerIp
DESCRIPTION:
Returns the IP address of the machine the server runs on
RETURN VALUES:
ra_ip_t rc the IP in network byte order
------------------------------------------------------------------------------
*/
ra_ip_t raGetServerIp()
------------------------------------------------------------------------------
FUNCTION NAME: raGetServerPort
DESCRIPTION:
Returns the Port number used by the raserver.
RETURN VALUES:
ra_port_t rc the port in network byte order
------------------------------------------------------------------------------
*/
ra_port_t raGetServerPort()
------------------------------------------------------------------------------
FUNCTION NAME: raSetPeriod
DESCRIPTION:
Sets the period in which the periodic event is called.
RETURN VALUES:
int rc == 0: The period was set
int rc != 0: An internal error
------------------------------------------------------------------------------
*/
int raSetPeriod(
struct timeval period /* r: period to be used */
)
------------------------------------------------------------------------------
FUNCTION NAME: raMem2Net
DESCRIPTION:
Converts a memory buffer into a 0 terminated string that can
be sent via raudp.
0 is represented as 0x0203
1 is represented as 0x0204
2 is represented as 0x0205
RETURN VALUES:
char * retptr != NULL: a 0 terminated string in static memory
otherwise: Out of memory
------------------------------------------------------------------------------
*/
char * raMem2Net(
char * from, /* IN: pointer to data to convert */
size_t len /* IN: length of that data */
)
------------------------------------------------------------------------------
FUNCTION NAME: raNet2Mem
DESCRIPTION:
Converts a raupd network string into a memory buffer
0x0203 is converted to 0
0x0204 is converted to 1
0x0205 is converted to 2
RETURN VALUES:
char * retptr != NULL: the decoded buffer in static memory
the length is set to output parameter tolen
otherwise: Out of memory
------------------------------------------------------------------------------
*/
char * raNet2Mem(
char * from, /* IN: pointer to string to convert */
size_t * tolen /* OUT: length of output data */
)
The following API Calls exist for UDP requests.
6.1. raGetArg
contents
------------------------------------------------------------------------------
FUNCTION NAME: raGetArg
DESCRIPTION:
Returns the i'th argument string given by the last call to
raEventUdpRequest.
Use it to retrieve the arguments one by one after a succesful call
to raEventUdpRequest.
RETURN VALUES:
char * retptr == NULL: index is out of bounds
------------------------------------------------------------------------------
*/
char * raGetArg(
char * psession, /* IN: pointer to client */
int index /* IN: index of argument to retrieve */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetClientIp
DESCRIPTION:
Returns the IP address of a client sending a udp request
RETURN VALUES:
ra_ip_t rc the IP in network byte order
------------------------------------------------------------------------------
*/
ra_ip_t raGetClientIp(
char * psession /* IN: pointer to client */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetClientPort
DESCRIPTION:
Returns the Port number used by a client sending a udp request
RETURN VALUES:
ra_port_t rc the port in network byte order
------------------------------------------------------------------------------
*/
ra_port_t raGetClientPort(
char * psession /* IN: pointer to client */
)
------------------------------------------------------------------------------
FUNCTION NAME: raSetResult
DESCRIPTION:
Sets the next result string in a call to raEventUdpRequest.
RETURN VALUES:
int rc >= 0: ok, length of total bytes set up to now is returned
int rc < 0: error, total of results set exceeds buffer size
------------------------------------------------------------------------------
*/
int raSetResult(
char * psession, /* IN: pointer to client */
char * result /* IN: result to set */
)
------------------------------------------------------------------------------
FUNCTION NAME: raClearResult
DESCRIPTION:
Clears the result buffer, should be called when raSetResult
reports an error.
RETURN VALUES:
int rc == 0: returns always 0
------------------------------------------------------------------------------
*/
int raClearResult(
char * psession /* IN: pointer to client */
)
7.1. raGetHttpClientIp
contents
------------------------------------------------------------------------------
FUNCTION NAME: raGetHttpClientIp
DESCRIPTION:
Returns the IP address of a connection sending a http request
RETURN VALUES:
ra_ip_t rc the IP in network byte order
------------------------------------------------------------------------------
*/
ra_ip_t raGetHttpClientIp(
char * pconnection /* IN: pointer to connection */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetHttpClientPort
DESCRIPTION:
Returns the Port number used by a client sending a http request
RETURN VALUES:
ra_port_t rc the port in network byte order
------------------------------------------------------------------------------
*/
ra_port_t raGetHttpClientPort(
char * pconnection /* IN: pointer to connection */
)
------------------------------------------------------------------------------
FUNCTION NAME: raSetHttpResult
DESCRIPTION:
Sets the next result string in a call to raEventHttpRequest.
RETURN VALUES:
unsigned rc > 0: ok, length of total bytes set up to now is returned
unsigned rc = 0: error, out of memory
------------------------------------------------------------------------------
*/
unsigned long raSetHttpResult(
char * pconnection, /* IN: pointer to connection */
char * result /* IN: result to set */
)
------------------------------------------------------------------------------
FUNCTION NAME: raClearHttpResult
DESCRIPTION:
Clears the result buffer, should be called when raSetHttpResult
reports an error.
RETURN VALUES:
int rc == 0: returns always 0
------------------------------------------------------------------------------
*/
int raClearHttpResult(
char * pconnection /* IN: pointer to connection */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetHttpHeader
DESCRIPTION:
Returns the header sent in a request
RETURN VALUES:
ptr to the header in memory
------------------------------------------------------------------------------
*/
char * raGetHttpHeader(
char * pconnection, /* IN: pointer to connection */
size_t * len /* OUT: length of header */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetHttpContent
DESCRIPTION:
Returns the content sent in a POST request
RETURN VALUES:
char * retptr == NULL: the request was a GET request, no content is given
otherwise: ptr to the content in memory
------------------------------------------------------------------------------
*/
char * raGetHttpContent(
char * pconnection, /* IN: pointer to connection */
size_t * len /* OUT: length of content */
)
------------------------------------------------------------------------------
FUNCTION NAME: raGetHttpUrl
DESCRIPTION:
Returns the url sent in a request, in the GET case this url
contains the parameters given.
RETURN VALUES:
char * retptr == NULL: no url was given
otherwise: ptr to the url in memory
------------------------------------------------------------------------------
*/
char * raGetHttpUrl(
char * pconnection, /* IN: pointer to connection */
size_t * len /* OUT: length of url */
)
The following client blocking UDP API calls exist.
8.1. raclient_udp_create
contents
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_create
DESCRIPTION:
Creates a remote access client udp structure, the structure can be
used in raclient_udp_request calls.
Delete the structure with raclient_udp_delete once you don't need
it anymore.
RETURN VALUES:
raclient_udp_t * retptr == NULL: Error, out of memory
retptr != NULL: a remote access client structure to use
------------------------------------------------------------------------------
*/
char * raclient_udp_create(
char * hostname, /* IN: name of host RA server is running on */
int port, /* IN: port of RA server, in host byte order */
time_t timeout, /* IN: seconds between retries */
int nretries /* IN: number of retries to attempt */
)
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_delete
DESCRIPTION:
Deletes a remote access client udp structure.
Do not use the pointer after calling this function.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raclient_udp_delete(
char * pclient /* IN: pointer to client */
)
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_error
DESCRIPTION:
Returns the error string set by the last call raclient_udp_request.
Use it to retrieve a detailed error string when raclient_udp_request
failes.
RETURN VALUES:
char * retptr: points to the error string set.
------------------------------------------------------------------------------
*/
char * raclient_udp_error(
char * pclient /* IN: pointer to client */
)
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_result
DESCRIPTION:
Returns the i'th result string returned by the last call to
raclient_udp_request.
Use it to retrieve the results one by one after a succesful call
to raclient_udp_request.
RETURN VALUES:
char * retptr == NULL: index is out of bounds
retptr != NULL: pointer to the i'th result, a '\0' terminated string.
The result is stored in static memory, subsequent
calls to raclient_udp_request() will reuse that
memory.
------------------------------------------------------------------------------
*/
char * raclient_udp_result(
char * pclient, /* IN: pointer to client */
int index /* IN: index of result to retrieve */
)
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_request
DESCRIPTION:
This function sends a UDP request to the ra server specified
in raclient_udp_create. The call is blocking and only returns
when either a result is received, the request is denied by the
server or a timeout occurs.
The request is sent via UDP, therefore the total number of the arguments
is limited by the size of a UDP packet, RA_MAX_SIZE_ARGUMENTS bytes.
The total size of the result values is also limited by that size.
RETURN VALUES:
int rc < 0: An error occured, see raclient_udp_error() for details.
Error code are defined in raextern.h.
int rc >= 0: Number of results sent back from the raserver.
Use raclient_udp_result() to retrieve them.
Note: The values of the result are stored in static memory, subsequent
calls to this function will overwrite them.
------------------------------------------------------------------------------
*/
int raclient_udp_request(
char * pclient, /* IN: pointer to client */
int inargc, /* IN: number of arguments that follow */
char * inargv[] /* IN: pointers array of arguments */
)
------------------------------------------------------------------------------
FUNCTION NAME: raclient_udp_multiple
DESCRIPTION:
This frunction reads udp requests from stream infile.
Each line read from infile is treated as a seperate request.
Each whitespace separated word of a line is sent as a
seperate request parameter. If words have to contain spaces
they can be quoted.
Ex: "this space" sends
this space
as one word to the server.
If quoted words have to contain ", they can be escaped with \
Ex: "the \" starts a quote" sends
the " starts a quote
as one word to the server.
For each request the results sent back by the raserver are
printed on outfile. Each result parameter on a seperate line.
RETURN VALUES:
int rc < 0: An error occured, see raclient_udp_error() for details.
Error code are defined in raextern.h.
int rc >= 0: Total number of results sent back from the raserver.
Each of them is already printed on outfile on a seperate
line.
------------------------------------------------------------------------------
*/
int raclient_udp_multiple(
char * pclient, /* IN: pointer to client */
FILE * infile, /* IN: stream to read aruments from */
FILE * outfile /* IN: stream to print results to */
)
The following client non blocking UDP API calls exist.
9.1. raCreateClient
contents
------------------------------------------------------------------------------
FUNCTION NAME: raCreateClient
DESCRIPTION:
Creates a remote access client udp structure, the structure can be
used in raUdpRequest calls.
Delete the structure with raDeleteClient once you don't need
it anymore.
RETURN VALUES:
raclient_udp_t * retptr == NULL: Error, out of memory
retptr != NULL: a remote access client structure to use
------------------------------------------------------------------------------
*/
char * raCreateClient(
char * hostname, /* IN: name of host RA server is running on */
int port, /* IN: port of RA server, in host byte order */
time_t timeout, /* IN: seconds between retries */
int nretries /* IN: number of retries to attempt */
)
------------------------------------------------------------------------------
FUNCTION NAME: raDeleteClient
DESCRIPTION:
Deletes a remote access client udp structure.
Do not use the pointer after calling this function.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void raDeleteClient(
char * pclient /* IN: pointer to client */
)
------------------------------------------------------------------------------
FUNCTION NAME: raRequestError
DESCRIPTION:
This function is to be called from the handler function of
an raUdpRequest() call.
It returns a detailed error string when raUdpRequest()
reports an error to the reply handler function.
RETURN VALUES:
char * retptr: points to the error string set.
------------------------------------------------------------------------------
*/
char * raRequestError(
char * prequest /* IN: pointer to request */
)
------------------------------------------------------------------------------
FUNCTION NAME: raRequestResult
DESCRIPTION:
This function is to be called from the handler function of
an raUdpRequest() call.
It returns the i'th result string returned by the
remote acces call.
Use it to retrieve the results one by one after a succesful call
to raUdpRequest().
RETURN VALUES:
char * retptr == NULL: index is out of bounds
retptr != NULL: pointer to the i'th result, a '\0' terminated string.
The result is stored in heap memory.
This memory will be freed after your handler
function returns.
------------------------------------------------------------------------------
*/
char * raRequestResult(
char * prequest, /* IN: pointer to request */
int index /* IN: index of result to retrieve */
)
------------------------------------------------------------------------------
FUNCTION NAME: raUdpRequest
DESCRIPTION:
This function sends a UDP request to the ra server specified
in raCreateClient.
The call is non blocking and returns immediatedly.
When either a result is received or the request is denied by the
server or a timeout occurs, the handler function specified here
as parameter is called. This handler function then has to
handle the results.
The interface to the handler function is as follows:
void handler(
char * request,
void * userdata,
int rc
)
Use the parameter "request" in subsequent calls to raRequestResult()
or raRequestError() in case of an error.
The parameter "userdata" is the userdata parameter as supplied to
this function.
The parameter "rc" contains the return code of the database request made.
If rc >= 0: Number of arguments returned by the database request.
Use raRequestResult() to retrieve them one by one.
If rc < 0: An error occured, error codes are defined in raextern.h.
Use the function raRequestError() to retrieve a description.
The request is sent via UDP, therefore the total number of the arguments
is limited by the size of a UDP packet, RA_MAX_SIZE_ARGUMENTS bytes.
The total size of the result values is also limited by that size.
RETURN VALUES:
int rc < 0: An error occured, see raRequestError() for details.
Error code are defined in raextern.h.
int rc == 0: The request was sent successfully.
------------------------------------------------------------------------------
*/
int raUdpRequest(
int socket, /* IN: socket to send through */
char * pclient, /* IN: pointer to udp request client */
int inargc, /* IN: number of arguments that follow */
char * inargv[], /* IN: pointers array of arguments */
raHandlerReplyPtr_t handler, /* IN: handler function called on reply */
void * userdata /* IN: user data passed on to handler */
)
Not yet implemented.
11. Command Line Tools
contents
------------------------------------------------------------------------------
FUNCTION NAME: main
DESCRIPTION:
This program calls the Remote Access server specified with the -r option
with all other arguments given.
Each request is sent via UDP, therefore the total number of the arguments
is limited by the size of a UDP packet, RA_MAX_SIZE_ARGUMENTS bytes.
The total size of the result values is also limited by that size.
If the first argument given is "-", the function reads lines of
UDP request parameters from stdin.
Each line read from infile is treated as a seperate request.
Each whitespace separated word of a line is sent as a
seperate request parameter. If words have to contain spaces
they can be quoted.
Ex: "this space" sends
this space
as one word to the server.
If quoted words have to contain ", they can be escaped with \
Ex: "the \" starts a quote" sends
the " starts a quote
as one word to the server.
For each request the results sent back by the raserver are
printed on stdout. Each result parameter on a seperate line.
EXAMPLE:
raudp -r localhost:2070 -BSIROOT /services/bsi arg1 arg2
arg1 arg2 are sent to the raserver.
raudp -r localhost:2070 -BSIROOT /services/bsi -
contents of stdin are sent to the raserver.
RETURN VALUES:
int exitcode != 0: An error occured, the error is printed on stdout.
int exitcode == 0: All return arguments are printed on stdout on
separate lines.
------------------------------------------------------------------------------
*/
int main(
int argc, /* IN: number of arguments that follow */
char * argv[] /* IN: pointers array of arguments */
)
{
static char usage[] =
"Usage %s -r raserver:port -BSIROOT rootdir [ arg1 arg2 .... ]\n\
where\n\
-r raserver:port hostname and port of raserver to call\n\
arg1 arg2 ... arguments to send to the server\n\
if arg1 == -, arguments are read from stdin\"";
------------------------------------------------------------------------------
FUNCTION NAME: main
DESCRIPTION:
This program calls the Remote Access server specified with the -r option
with all other arguments given.
Each request is sent via TCP, therefore the total number of the arguments
is limited by the size of a UDP packet, RA_MAX_SIZE_ARGUMENTS bytes.
EXAMPLE:
raudp -r localhost:2070 -BSIROOT /services/bsi arg1 arg2
arg1 arg2 are sent to the raserver.
RETURN VALUES:
int exitcode != 0: An error occured, the error is printed on stdout.
int exitcode == 0: All return arguments are printed on stdout on
separate lines.
------------------------------------------------------------------------------
*/
int main(
int argc, /* IN: number of arguments that follow */
char * argv[] /* IN: pointers array of arguments */
)
{
static char usage[] =
"Usage %s -r raserver:port -BSIROOT rootdir [ arg1 arg2 .... ]\n\
where\n\
-r raserver:port hostname and port of raserver to call\n\
arg1 arg2 ... arguments to send to the server\n\
if arg1 == -, arguments are read from stdin\"";