Changeset 4659 for trunk/Nebulous/nebclient

Timestamp:

Jul 28, 2005, 4:30:42 PM (21 years ago)

Author:

jhoblitt

Message:

add doxygen

File:

• trunk/Nebulous/nebclient/src/nebclient.h (modified) (3 diffs)

trunk/Nebulous/nebclient/src/nebclient.h

@@ -4 +4 @@
  * 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 +15 @@
 extern "C" {
 #endif
+
+/// @addtogroup nebclient
+/// @{
 
 typedef enum { NEB_READ, NEB_WRITE } nebRW;
@@ -41 +44 @@
 } 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