notes.h in rugged-0.18.0.b1

- old
+ new

@@ -1,7 +1,7 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * Copyright (C) the libgit2 contributors. All rights reserved.
  *
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
 #ifndef INCLUDE_git_note_h__
@@ -17,41 +17,103 @@
  * @{
  */
 GIT_BEGIN_DECL
 
 /**
+ * Callback for git_note_foreach.
+ *
+ * Receives:
+ * - blob_id: Oid of the blob containing the message
+ * - annotated_object_id: Oid of the git object being annotated
+ * - payload: Payload data passed to `git_note_foreach`
+ */
+typedef int (*git_note_foreach_cb)(
+	const git_oid *blob_id, const git_oid *annotated_object_id, void *payload);
+
+/**
+ * note iterator
+ */
+typedef struct git_iterator git_note_iterator;
+
+/**
+ * Creates a new iterator for notes
+ *
+ * The iterator must be freed manually by the user.
+ *
+ * @param out pointer to the iterator
+ * @param repo repository where to look up the note
+ * @param notes_ref canonical name of the reference to use (optional); defaults to
+ *                  "refs/notes/commits"
+ *
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_note_iterator_new(
+	git_note_iterator **out,
+	git_repository *repo,
+	const char *notes_ref);
+
+/**
+ * Frees an git_note_iterator
+ *
+ * @param it pointer to the iterator
+ */
+GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it);
+
+/**
+ * Returns the current item (note_id and annotated_id) and advance the iterator
+ * internally to the next value
+ *
+ * The notes must not be freed manually by the user.
+ *
+ * @param it pointer to the iterator
+ * @param note_id id of blob containing the message
+ * @param annotated_id id of the git object being annotated
+ *
+ * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code
+ *         (negative value)
+ */
+GIT_EXTERN(int) git_note_next(
+	git_oid* note_id,
+	git_oid* annotated_id,
+	git_note_iterator *it);
+
+
+/**
  * Read the note for an object
  *
  * The note must be freed manually by the user.
  *
- * @param note pointer to the read note; NULL in case of error
+ * @param out pointer to the read note; NULL in case of error
  * @param repo repository where to look up the note
- * @param notes_ref canonical name of the reference to use (optional);
- *					defaults to "refs/notes/commits"
+ * @param notes_ref canonical name of the reference to use (optional); defaults to
+ *                  "refs/notes/commits"
  * @param oid OID of the git object to read the note from
  *
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_note_read(git_note **note, git_repository *repo,
-			      const char *notes_ref, const git_oid *oid);
+GIT_EXTERN(int) git_note_read(
+	git_note **out,
+	git_repository *repo,
+	const char *notes_ref,
+	const git_oid *oid);
 
 /**
  * Get the note message
  *
  * @param note
  * @return the note message
  */
-GIT_EXTERN(const char *) git_note_message(git_note *note);
+GIT_EXTERN(const char *) git_note_message(const git_note *note);
 
 
 /**
  * Get the note object OID
  *
  * @param note
  * @return the note object OID
  */
-GIT_EXTERN(const git_oid *) git_note_oid(git_note *note);
+GIT_EXTERN(const git_oid *) git_note_oid(const git_note *note);
 
 /**
  * Add a note for an object
  *
  * @param out pointer to store the OID (optional); NULL in case of error
@@ -60,17 +122,23 @@
  * @param committer signature of the notes commit committer
  * @param notes_ref canonical name of the reference to use (optional);
  *					defaults to "refs/notes/commits"
  * @param oid OID of the git object to decorate
  * @param note Content of the note to add for object oid
+ * @param force Overwrite existing note
  *
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_note_create(git_oid *out, git_repository *repo,
-				git_signature *author, git_signature *committer,
-				const char *notes_ref, const git_oid *oid,
-				 const char *note);
+GIT_EXTERN(int) git_note_create(
+	git_oid *out,
+	git_repository *repo,
+	const git_signature *author,
+	const git_signature *committer,
+	const char *notes_ref,
+	const git_oid *oid,
+	const char *note,
+	int force);
 
 
 /**
  * Remove the note for an object
  *
@@ -81,13 +149,16 @@
  * @param committer signature of the notes commit committer
  * @param oid OID of the git object to remove the note from
  *
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_note_remove(git_repository *repo, const char *notes_ref,
-				git_signature *author, git_signature *committer,
-				const git_oid *oid);
+GIT_EXTERN(int) git_note_remove(
+	git_repository *repo,
+	const char *notes_ref,
+	const git_signature *author,
+	const git_signature *committer,
+	const git_oid *oid);
 
 /**
  * Free a git_note object
  *
  * @param note git_note object
@@ -103,21 +174,10 @@
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_note_default_ref(const char **out, git_repository *repo);
 
 /**
- * Basic components of a note
- *
- *  - Oid of the blob containing the message
- *  - Oid of the git object being annotated
- */
-typedef struct {
-	git_oid blob_oid;
-	git_oid annotated_object_oid;
-} git_note_data;
-
-/**
  * Loop over all the notes within a specified namespace
  * and issue a callback for each one.
  *
  * @param repo Repository where to find the notes.
  *
@@ -132,12 +192,11 @@
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_note_foreach(
 	git_repository *repo,
 	const char *notes_ref,
-	int (*note_cb)(git_note_data *note_data, void *payload),
-	void *payload
-);
+	git_note_foreach_cb note_cb,
+	void *payload);
 
 /** @} */
 GIT_END_DECL
 #endif