VACM: Users and Programmers Manual
Prev		Next

Chapter 9. Writing VACM Clients

Table of Contents
Libvacmclient function prototypes
An Example Client

VACM Clients are the interface between the user and Nexxus. They dispatch the IPC commands to Nexxus and present the responses to the user in either a raw or a cooked format. As VACM installations evolve it is possible to have a highly customized client which reacts to your special set of rules. VACM Clients, like Modules, are stand alone programs. They can be launched at any time by users or by scripts to perform given tasks.

Libvacmclient function prototypes

Clients should be written using the VACM Client API defined below. To use this API we just need to include vacmclient_api.h and to link with libvacmclient.a.
int api_nexxus_connect(char *addr, char *username, char *password, void **new_handle);
Connect to the given nexxus with username and password via an AF_INET socket. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure.

int api_nexxus_disconnect(void *handle);
Disconnect from the nexxus associated with handle. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure.

int api_nexxus_send_ipc(void *handle, char *pkt, __uint32_t len);
Sends an IPC message of length len to the Nexxus associated with handle.

int api_nexxus_recv_ipc(void *handle, char **buffer, __uint32_t *len);
Read an IPC message from the Nexxus associated with handle. The length of the message read is stored in len. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure. It is the callers responsibility to free buffer.

int api_nexxus_wait_for_data(void *handle, char **buffer, __uint32_t *len, int timeout);
Waits for IPC data from the Nexxus associated with handle with a timeout of 'timeout' seconds. Returns API_RETURN_OK on success, < 0 with vacm_Errno set on failure. On success, it is the caller's responsibility to free buffer.

int api_nexxus_wait_short_for_data(void *handle, char **buffer, __uint32_t *len, int timeout);
Identical to api_nexxus_wait_for_data except timeout is a length in microseconds instead of seconds.

int api_nexxus_return_fd(void *handle, int fd);
Gets the file descriptor of the Nexxus asssociated with handle. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure.

int api_nexxus_return_ip(void *handle, struct in_addr *ip_addr);
Get the ip address of the Nexxus associated with handle. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure. -1 on failure with vacm_errno set.

int api_nexxus_return_handle(void **handle, char *addr);
Get the handle associated with the nexxus at *addr. Returns API_RETURN_OK on success, < 0 with vacm_errno set on failure.

void api_nexxus_perror(char *msg);
Similar to perror(char *), but prints the value of vacm_errno.

char *api_nexxus_get_error(void);
Returns the stringified version of vacm_errno.

int api_nexxus_ping(struct in_addr *ip_addr, struct timeval *timeout);
Sends a ping message to the remote host specified by 'in_addr' and waits for a period specified by ´timeout'. Returns API_RETURN_OK if the remote host has a Nexxus running, API_RETURN_TIMED_OUT if the remote host was not running a Nexxus, and API_RETURN_MISC_ERROR on error.