more task functionality

lib/taskchampion.h

@@ -4,11 +4,32 @@
 #include <ostream>
 #include <new>
 
+/// The status of a task, as defined by the task data model.
+enum TCStatus {
+  TC_STATUS_PENDING,
+  TC_STATUS_COMPLETED,
+  TC_STATUS_DELETED,
+  /// Unknown signifies a status in the task DB that was not
+  /// recognized.
+  TC_STATUS_UNKNOWN,
+};
+
 /// A replica represents an instance of a user's task data, providing an easy interface
 /// for querying and modifying that data.
 struct TCReplica;
 
+/// TCString supports passing strings into and out of the TaskChampion API.
+struct TCString;
+
+/// A task, as publicly exposed by this library.
+///
+/// A task carries no reference to the replica that created it, and can
+/// be used until it is freed or converted to a TaskMut.
+struct TCTask;
+
 /// TCUuid is used as a task identifier.  Uuids do not contain any pointers and need not be freed.
+/// Uuids are typically treated as opaque, but the bytes are available in big-endian format.
+///
 struct TCUuid {
   uint8_t bytes[16];
 };
@@ -27,6 +48,11 @@ extern const uintptr_t TC_UUID_STRING_BYTES;
 /// TCReplicas are not threadsafe.
 TCReplica *tc_replica_new(const char *path);
 
+/// Create a new task.  The task must not already exist.
+///
+/// Returns the task, or NULL on error.
+TCTask *tc_replica_new_task(TCReplica *rep, TCStatus status, TCString *description);
+
 /// Undo local operations until the most recent UndoPoint.
 ///
 /// Returns -1 on error, 0 if there are no local operations to undo, and 1 if operations were
@@ -41,6 +67,25 @@ const char *tc_replica_error(TCReplica *rep);
 /// Free a TCReplica.
 void tc_replica_free(TCReplica *rep);
 
+TCString *tc_string_new(const char *cstr);
+
+const char *tc_string_content(TCString *string);
+
+void tc_string_free(TCString *string);
+
+/// Get a task's UUID.
+TCUuid tc_task_get_uuid(const TCTask *task);
+
+/// Get a task's status.
+TCStatus tc_task_get_status(const TCTask *task);
+
+/// Get a task's description, or NULL if the task cannot be represented as a C string (e.g., if it
+/// contains embedded NUL characters).
+TCString *tc_task_get_description(const TCTask *task);
+
+/// Free a task.
+void tc_task_free(TCTask *task);
+
 /// Create a new, randomly-generated UUID.
 TCUuid tc_uuid_new_v4();