AceConn - a C package for accessing the Acedb Server

ACEDB AceConn Library

AceConn - a C library for accessing the Acedb Server

Originally written by
Ed Griffiths <edgrif@sanger.ac.uk>, March 2002

Background

The introduction of a sockets based server for Acedb has allowed perl, python and java based clients easy access to the server as these languages already provide good packages for using sockets. The AceConn library provides a simple C library which can be used to communicate with the server making it just as easy to write C programs that can access the Acedb server.
The AceConn library is independent of the main acedb code making it easy to compile on most machines. The AceConn package makes use of some public MD5 code for encrypting passwords and the test code makes use of the GNU getopt routines, both of these are included in the package. Otherwise the only external dependency is on the GTK glib library which is now widely installed on many machines and freely available from the GTK web site.
Programming Overview

Requests and Replies

All requests must be valid C strings with the usual terminating NULL character. The request should be one of those supported by the command line variants of the acedb programs, see the tace or giface documentation for lists of these commands.
The reply can be either a valid C string or data in some other format such as a postscript image. Therefore the reply is in the form of a buffer with a separate length. Note that for a C string the returned length includes the terminating NULL character.
Note the implication of this: the calling program can only tell what sort of data is returned from the request that it sent over. It is the applications responsibility to keep track of this.
Neither the request string nor the reply buffer are ever free'd by the AceConn library, it is the applications responsibility to free them. The request string is allocated by the application and should be free'd accordingly. The reply buffer is allocated by the library using the glib g_malloc() function and should be released with the g_free() function.
Library errors

The error strategy employed in the library is to return an AceConnStatus for all interface functions to indicate any error. If the connection was not released by the interface function (e.g. as for AceConnRequest()) then a text string describing the error can be retrieved using AceConnGetLastErrMsg().
Note that you should only use AceConnGetLastErrMsg() when there has been an error and the connection is still valid:
    status = AceConnRequest() ;
    if (status != ACECONN_OK && AceConnIsValid(connection))
      err_msg = AceConnGetLastErrMsg(connection) ;
Once an error has been detected for a connection, that connection should be closed using AceConnDisconnect(). The results are undefined if you continue to try to use a connection after an error.
Where the library changed some global aspect of the applications state (e.g. signal handlers), the library restores that state before returning, even when there has been an error.
The functions can return the following AceConnStatus values:

ACECONN_OK
No error.
ACECONN_QUIT
request sent to server was "quit" so connection is now closed.
ACECONN_INVALIDCONN
connection points to invalid memory.
ACECONN_BADARGS
caller has supplied bad args.
ACECONN_NOSOCK
socket creation problem.
ACECONN_UNKNOWNHOST
serrver host not known.
ACECONN_NOCONNECT
could not connect to host.
ACECONN_NOSELECT
select on socket failed.
ACECONN_HANDSHAKE
handshake to server failed.
ACECONN_READERROR
error in reading from socket.
ACECONN_WRITEERROR
error in writing to socket.
ACECONN_SIGSET
problem with signal setting.
ACECONN_NONBLOCK
non-blocking for socket failed.
ACECONN_TIMEDOUT
connection timed out.
ACECONN_NOCREATE
could not create connection control block.
ACECONN_INTERNAL
Dire internal package error.

Usage

See the test programs that come with the AceConn library which provide typical examples of how to use the library.
Interface Functions

Header files

You must include the AceConn header file in your code:
#include <AceConn.h>
AceConnConnect - Open a connection to the Acedb server.

Synopsis:
AceConnStatus AceConnConnect(AceConnection *connection,
			     char *server_netid, int server_port,
			     char *userid, char *passwd, int timeout) ;
Parameters:

connection
The returned valid connection to the server.
server_netid
The network id of the Acedb server.
server_port
The port on the server_netid machine where the Acedb server can be accessed.
userid
The users Acedb userid as held in the acedb database.
passwd
The users Acedb password as held in the acedb database.
timeout
Time in seconds to wait for the Acedb server to respond, if this time is exceeded the call will return with a status of ACECONN_TIMEDOUT. Time out values have the following meanings:

< 0 - reset timeout to default value (120 seconds).
0 - never timeout, i.e. wait indefinitely for a reply.
> 0 - means set timeout to this value.

Description: Connects to the server, does the user/password handshaking and returns a valid connection. The returned connection can be used to send Acedb commands to the server and get the returned replies.
Notes: If the call fails, no connection is returned. This means the cause of the error can only be determined from the returned AceConnStatus value, the AceConnGetLastErrMsg() call cannot be used to get the associated error message.
Return Values: Upon successful completion, the AceConnConnect() function returns ACECONN_OK and a valid AceConnection in the *connection parameter. If there was an error the AceConnStatus value will indicate the nature of the error and the *connection parameter will be unchanged.
AceConnRequest - Make a request to, and receive the reply from, the Acedb server.

Synopsis:
AceConnStatus AceConnConnect(AceConnection *connection,
			     char *request,
			     void **reply, int *reply_len) ;
Parameters:

connection
A valid connection.
request
The Acedb command to send to the server.
reply
The returned reply from the server.
reply_len
The length of the reply from the server.

Description: Sends a request to the server and then collects the reply. The Acedb server may send back the reply in a number of "slices", if this happens the call returns only when all the slices have been sent back and reassembled into a single reply. The call will time out after timeout seconds.
Return Values: Upon successful completion, the AceConnConnect() function returns ACECONN_OK and returns the reply in the reply and reply_len parameters. Otherwise an AceConnStatus value will indicating the nature of the error is returned and the reply and reply_len parameters are left unchanged. A text error message that can be retrieved with AceConnGetLastErrMsg().
AceConnDisconnect - Disconnect from the Acedb server.

Synopsis:
AceConnStatus AceConnDisconnect(AceConnection connection) ;
Parameters:

connection
A valid connection.

Description: Sends a termination request to the server, waits for the "end of session" message from the server and then tidies up the resources associated with the connection. The call will time out after timeout seconds.
Notes: If the call fails (e.g. it times out), the resources associated with the connection are still released so it is not possible to use AceConnGetLastErrMsg() to retrieve the last error message, only the returned AceConnStatus value indicates the nature of the error.
Return Values: Upon successful completion, the AceConnRequest() function returns ACECONN_OK. Whether there was an error or not all resources for the connection are released and the connection should not be used again.
Utility Functions

AceConnSetTimeout - Set the timeout for calls to the server.

Synopsis:
AceConnStatus AceConnSetTimeout(AceConnection connection, int timeout) ;
Parameters:

connection
A valid connection.
timeout
Time out in seconds, see timeout for a fuller description.

Description: Sets a new timeout value for the connection, this will cause all subsequent interface functions to time out after that many seconds.
Notes: Can only fail because connection is invalid in some way (e.g. NULL connection).
Return Values: Upon successful completion, the AceConnSetTimeout() function returns ACECONN_OK, and the new timeout value is set for the connection. If there is an error it is because there is something wrong with the connection parameter and so no action is taken. A text error message that can be retrieved with AceConnGetLastErrMsg().
AceConnGetLastErrMsg - Get a text description of the last error on the connection.

Synopsis:
char *AceConnGetLastErrMsg(AceConnection connection) ;
Parameters:

connection
A valid connection.

Description: Returns a string which describes in text form the last error detected by the connection code. You should not call this function unless an AceConn function has returned an error, otherwise the string returned maybe NULL or refer to a previous error.
Notes: Can only be used on a valid connection, the code will trap NULL or invalid connections and return NULL.
Return Values: Upon successful completion, the AceConnGetLastErrMsg() function returns a valid C string, you should not free or alter this string but instead take a copy of it if you need to use it in any way. If the connection is invalid, or if called when there has been no error, NULL is returned.
AceConnGetVersion - Get AceConn library version information

Synopsis:
char *AceConnGetVersion(guint *version, guint *release, guint *update) ;
Parameters:

version, release, update
the returned version, release and update of the library respectively.

Description: Returns as unsigned ints the version/release/update of the AceConn library. Allows testing of the library against the header and for overall release level, see the ACECONN_CHECK_VERSION() macro.
Return Values: For non-NULL parameters, the version, release and update of the library respectively are returned as unsigned ints.
Comments/Bugs

Please mail comments/bugs to Acedb Developers <acedb@sanger.ac.uk>

ACEDB AceConn Library

Ed Griffiths <edgrif@sanger.ac.uk>
Last modified: Fri May 23 10:20:09 BST 2003