Buflib: Clarification about invalid handles

* Enhance allocation function comments to better state the return value and what an invalid value is
* Change clients to check for "< 0" instead of "<= 0" or "== 0"
* Return -1 or -2 depending on the exact failure in buflib_alloc_ex.

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@30469 a1c6a512-1295-4272-9138-f99709370657

2 files changed, 9 insertions, 6 deletions

diff --git a/firmware/buflib.c b/firmware/buflib.c
index f7ef35ea8b..7c5f3d208e 100644
--- a/firmware/buflib.c
+++ b/firmware/buflib.c
@@ -425,7 +425,7 @@ handle_alloc:
                     goto handle_alloc;
                 }
             }
-            return 0;
+            return -1;
         }
     }
 
@@ -471,7 +471,7 @@ buffer_alloc:
         } else {
             handle->val=1;
             handle_free(ctx, handle);
-            return 0;
+            return -2;
         }
     }
 
diff --git a/firmware/include/buflib.h b/firmware/include/buflib.h
index db7b5ec50a..3d8f43ef5f 100644
--- a/firmware/include/buflib.h
+++ b/firmware/include/buflib.h
@@ -153,7 +153,8 @@ size_t buflib_available(struct buflib_context *ctx);
  *
  * size: How many bytes to allocate
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc(struct buflib_context *context, size_t size);
 
@@ -166,7 +167,8 @@ int buflib_alloc(struct buflib_context *context, size_t size);
  * size: How many bytes to allocate
  * ops: a struct with pointers to callback functions (see above)
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc_ex(struct buflib_context *ctx, size_t size, const char *name,
                     struct buflib_callbacks *ops);
@@ -188,7 +190,8 @@ int buflib_alloc_ex(struct buflib_context *ctx, size_t size, const char *name,
  * size: The actual size will be returned into size
  * ops: a struct with pointers to callback functions
  *
- * Returns: An integer handle identifying this allocation
+ * Returns: A positive integer handle identifying this allocation, or
+ * a negative value on error (0 is also not a valid handle)
  */
 int buflib_alloc_maximum(struct buflib_context* ctx, const char* name,
                     size_t *size, struct buflib_callbacks *ops);
@@ -233,7 +236,7 @@ bool buflib_shrink(struct buflib_context *ctx, int handle, void* newstart, size_
 /**
  * Frees memory associated with the given handle
  *
- * Returns: 0 (to invalidate handles in one line)
+ * Returns: 0 (to invalidate handles in one line, 0 is not a valid handle)
  */
 int buflib_free(struct buflib_context *context, int handle);