Index: trunk/Nebulous/nebclient/src/nebclient.h =================================================================== --- trunk/Nebulous/nebclient/src/nebclient.h (revision 4657) +++ trunk/Nebulous/nebclient/src/nebclient.h (revision 4659) @@ -4,5 +4,5 @@ * Copyright (C) 2005 Joshua Hoblitt * - * $Id: nebclient.h,v 1.25 2005-07-29 01:49:30 jhoblitt Exp $ + * $Id: nebclient.h,v 1.26 2005-07-29 02:30:42 jhoblitt Exp $ */ @@ -15,4 +15,7 @@ extern "C" { #endif + +/// @addtogroup nebclient +/// @{ typedef enum { NEB_READ, NEB_WRITE } nebRW; @@ -41,39 +44,198 @@ } nebObjectInstances; -nebServer *nebServerAlloc(const char *endpoint); - -void nebServerCleanup(nebServer *server); - -int nebCreate(nebServer *server, const char *key, unsigned int class, const char *volume, const char *comment, char **URI); - -bool nebReplicate(nebServer *server, const char *key, const char *volume, char **URI); - -bool nebCull(nebServer *server, const char *key); - -bool nebLock(nebServer *server, const char *key, nebRW flag); - -bool nebUnlock(nebServer *server, const char *key, nebRW flag); - -nebObjectInstances *nebFindInstances(nebServer *server, const char *key, const char *volume); - -void nebObjectInstancesFree(nebObjectInstances *locations); - -char *nebFind(nebServer *server, const char *key); - -int nebOpen(nebServer *server, const char *key, nebRW flag); - -bool nebDelete(nebServer *server, const char *key); - -bool nebCopy(nebServer *server, const char *key, const char *newKey); - -bool nebMove(nebServer *server, const char *key, const char *newKey); - -bool nebDeleteInstance(nebServer *server, const char *URI); - -nebObjectStat *nebStat(nebServer *server, const char *key); - -char *nebErr(nebServer *server); - +/** Allocates a nebServer object + * + * Structure used for communicating with a Nebulous server. If endpoint is + * NULL then the default value of "http://localhost:80/nebulous" is used. + * + * @return A nebServer object or NULL on failure. + */ + +nebServer *nebServerAlloc( + const char *endpoint ///< URL of server +); + +/** Deallocates a nebServer object + */ + +void nebServerCleanup( + nebServer *server ///< nebServer object +); + +/** Creates and opens new storage object + * + * @return A filehandle on success or a negative value on failure. + */ + +int nebCreate( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + unsigned int class, ///< storage object storage class + const char *volume, ///< preferred storage location of initial instance + const char *comment, ///< storage object comment + char **URI ///< URL of initial instance, can be NULL +); + +/** Adds an instance to a storage object + * + * @return true on success + */ + +bool nebReplicate( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + const char *volume, ///< preferred storage location of new instance + char **URI ///< URL of new instance, can be NULL +); + +/** Removes an instance from a storage object + * + * This function can not remove the last instance of a storage object. + * + * @return true on success + */ + +bool nebCull( + nebServer *server, ///< nebServer object + const char *key ///< storage object ID +); + +/** Trys to acquire a lock on a storage object + * + * This function times out after a default interval of 10s (compile time + * configurable). + * + * @return true on success + */ +bool nebLock( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + nebRW flag ///< read only or write lock +); + +/** Trys to release a lock on a storage object + * + * @return true on success + */ +bool nebUnlock( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + nebRW flag ///< read only or write lock +); + +/** Lists all instances of a storage object + * + * @return A nebObjectInstances object or NULL on failure. + */ + +nebObjectInstances *nebFindInstances( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + const char *volume ///< restrict search to this storage volume (non-working) +); + +/** Deallocates a nebObjectInstances object + */ + +void nebObjectInstancesFree( + nebObjectInstances *locations ///< nebObjectInstances object to free +); + +/** Find any instance of a storage object + * + * @return A string of the files storage path (not a URL) or NULL on failure. + */ + +char *nebFind( + nebServer *server, ///< nebServer object + const char *key ///< storage object ID +); + +/** Open a storage object for read or write + * + * @return A filehandle on success or a negative value on failure. + */ + +int nebOpen( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + nebRW flag ///< read only or write lock +); + +/** Delete a storage object and all of it's instances + * + * @return true on success + */ + +bool nebDelete( + nebServer *server, ///< nebServer object + const char *key ///< storage object ID +); + +/** Copy a storage object + * + * The new storage object will be created with only one instance. + * + * @return true on success + */ + +bool nebCopy( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + const char *newKey ///< new storage object ID +); + +/** Rename a storage object + * + * Currently this operation will remove all but one instance of the storage + * object and may change it's storage location. + */ +bool nebMove( + nebServer *server, ///< nebServer object + const char *key, ///< storage object ID + const char *newKey ///< new storage object ID +); + +/** Remove a storage object instance + * + * Removing the last instance of a storage object with destroy the storage + * object as well. + * + * @return true on success + */ + +bool nebDeleteInstance( + nebServer *server, ///< nebServer object + const char *URI ///< URL of instance to remove +); + +/** View the properties of a storage object + * + * @return A nebObjectStat object or NULL on failure. + */ + +nebObjectStat *nebStat( + nebServer *server, ///< nebServer object + const char *key /// storage object ID +); + +/** Returns the error message from the last nebclient function that failed. + * + * This function may not be called unless an error has occurred. The string + * return by this function does not need to be freed but the value will change + * at the next nebclient function failure. + * + * @return A string + */ + +char *nebErr( + nebServer *server ///< nebServer object +); + +/** Free nebclient allocated memory + */ void nebFree(void *ptr); + +/// @} #ifdef __cplusplus