[ostree] libostree: Add gtk-doc section for ostree-repo.c
- From: Colin Walters <walters src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [ostree] libostree: Add gtk-doc section for ostree-repo.c
- Date: Sat, 17 Aug 2013 17:23:33 +0000 (UTC)
commit 1fea88e64be8f09d3d81b2ae953612660963a606
Author: Colin Walters <walters verbum org>
Date: Sat Aug 17 13:22:58 2013 -0400
libostree: Add gtk-doc section for ostree-repo.c
doc/ostree-docs.xml | 1 +
doc/ostree-sections.txt | 64 ++++++++++++++++++++++++
src/libostree/ostree-repo-checkout.c | 3 +
src/libostree/ostree-repo.c | 90 ++++++++++++++++++++++++++++++----
src/libostree/ostree-repo.h | 22 ++++++---
5 files changed, 163 insertions(+), 17 deletions(-)
---
diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index 71561ac..3393655 100644
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -16,6 +16,7 @@
<chapter xml:id="reference">
<title>API Reference</title>
<xi:include href="xml/libostree-core.xml"/>
+ <xi:include href="xml/libostree-repo.xml"/>
<index id="api-index-full">
<title>API Index</title>
diff --git a/doc/ostree-sections.txt b/doc/ostree-sections.txt
index 9d293fa..98f1d03 100644
--- a/doc/ostree-sections.txt
+++ b/doc/ostree-sections.txt
@@ -61,3 +61,67 @@ ostree_validate_structureof_dirtree
ostree_validate_structureof_dirmeta
ostree_commit_get_parent
</SECTION>
+
+<SECTION>
+<FILE>libostree-repo</FILE>
+OstreeRepoMode
+ostree_repo_new
+ostree_repo_check
+ostree_repo_get_path
+ostree_repo_get_mode
+ostree_repo_mode_from_string
+ostree_repo_get_config
+ostree_repo_copy_config
+ostree_repo_get_parent
+ostree_repo_write_config
+ostree_repo_prepare_transaction
+ostree_repo_commit_transaction
+ostree_repo_commit_transaction_with_stats
+ostree_repo_abort_transaction
+ostree_repo_has_object
+ostree_repo_stage_metadata
+ostree_repo_stage_metadata_async
+ostree_repo_stage_metadata_finish
+ostree_repo_stage_metadata_trusted
+ostree_repo_stage_content
+ostree_repo_stage_content_trusted
+ostree_repo_stage_content_async
+ostree_repo_stage_content_finish
+ostree_repo_resolve_rev
+ostree_repo_write_ref
+ostree_repo_write_refspec
+ostree_repo_list_refs
+ostree_repo_load_variant_c
+ostree_repo_load_variant
+ostree_repo_load_variant_if_exists
+ostree_repo_load_file
+ostree_repo_load_object_stream
+ostree_repo_query_object_storage_size
+ostree_repo_delete_object
+OstreeRepoCommitFilterResult
+OstreeRepoCommitFilter
+OstreeRepoCommitModifier
+ostree_repo_commit_modifier_new
+ostree_repo_commit_modifier_ref
+ostree_repo_commit_modifier_unref
+ostree_repo_stage_directory_to_mtree
+ostree_repo_stage_archive_to_mtree
+ostree_repo_stage_mtree
+ostree_repo_stage_commit
+OstreeRepoCheckoutMode
+OstreeRepoCheckoutOverwriteMode
+ostree_repo_checkout_tree_async
+ostree_repo_checkout_tree_finish
+ostree_repo_checkout_gc
+ostree_repo_read_commit
+OstreeRepoListObjectsFlags
+OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE
+ostree_repo_list_objects
+ostree_repo_traverse_new_reachable
+ostree_repo_traverse_dirtree
+ostree_repo_traverse_commit
+OstreeRepoPruneFlags
+ostree_repo_prune
+OstreeRepoPullFlags
+ostree_repo_pull
+</SECTION>
diff --git a/src/libostree/ostree-repo-checkout.c b/src/libostree/ostree-repo-checkout.c
index c98cfcf..f9187ff 100644
--- a/src/libostree/ostree-repo-checkout.c
+++ b/src/libostree/ostree-repo-checkout.c
@@ -758,6 +758,9 @@ ostree_repo_checkout_tree_finish (OstreeRepo *self,
/**
* ostree_repo_checkout_gc:
+ * @self: Repo
+ * @cancellable: Cancellable
+ * @error: Error
*
* Call this after finishing a succession of checkout operations; it
* will delete any currently-unused uncompressed objects from the
diff --git a/src/libostree/ostree-repo.c b/src/libostree/ostree-repo.c
index 4fbd3a5..c7ff2aa 100644
--- a/src/libostree/ostree-repo.c
+++ b/src/libostree/ostree-repo.c
@@ -36,6 +36,31 @@
#include "libgsystem.h"
#include "ostree-repo-file-enumerator.h"
+/**
+ * SECTION:libostree-repo
+ * @title: Content-addressed object store
+ * @short_description: A git-like storage system for operating system binaries
+ *
+ * The #OstreeRepo is like git, a content-addressed object store.
+ * Unlike git, it records uid, gid, and extended attributes.
+ *
+ * There are two possible "modes" for an #OstreeRepo;
+ * %OSTREE_REPO_MODE_BARE is very simple - content files are
+ * represented exactly as they are, and checkouts are just hardlinks.
+ * A %OSTREE_REPO_MODE_ARCHIVE_Z2 repository in contrast stores
+ * content files zlib-compressed. It is suitable for non-root-owned
+ * repositories that can be served via a static HTTP server.
+ *
+ * To store content in the repo, first start a transaction with
+ * ostree_repo_prepare_transaction(). Then create a
+ * #OstreeMutableTree, and apply functions such as
+ * ostree_repo_stage_directory_to_mtree() to traverse a physical
+ * filesystem and stage content, possibly multiple times.
+ *
+ * Once the #OstreeMutableTree is complete, stage all of its metadata
+ * with ostree_repo_stage_mtree(), and finally create a commit with
+ * ostree_repo_stage_commit().
+ */
typedef struct {
GObjectClass parent_class;
} OstreeRepoClass;
@@ -983,6 +1008,13 @@ ostree_repo_abort_transaction (OstreeRepo *self,
/**
* ostree_repo_stage_metadata:
+ * @self: Repo
+ * @objtype: Object type
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Metadata
+ * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @cancellable: Cancellable
+ * @error: Error
*
* Store the metadata object @variant. Return the checksum
* as @out_csum.
@@ -992,9 +1024,9 @@ ostree_repo_abort_transaction (OstreeRepo *self,
*/
gboolean
ostree_repo_stage_metadata (OstreeRepo *self,
- OstreeObjectType type,
+ OstreeObjectType objtype,
const char *expected_checksum,
- GVariant *variant,
+ GVariant *object,
guchar **out_csum,
GCancellable *cancellable,
GError **error)
@@ -1002,18 +1034,24 @@ ostree_repo_stage_metadata (OstreeRepo *self,
gs_unref_object GInputStream *input = NULL;
gs_unref_variant GVariant *normalized = NULL;
- normalized = g_variant_get_normal_form (variant);
+ normalized = g_variant_get_normal_form (object);
input = ot_variant_read (normalized);
- return stage_object (self, type, expected_checksum, input, 0, out_csum,
+ return stage_object (self, objtype, expected_checksum, input, 0, out_csum,
cancellable, error);
}
/**
* ostree_repo_stage_metadata_trusted:
+ * @self: Repo
+ * @objtype: Object type
+ * @checksum: Store object with this ASCII SHA256 checksum
+ * @variant: Metadata object
+ * @cancellable: Cancellable
+ * @error: Error
*
- * Store the metadata object @variant; the provided @checksum
- * is trusted.
+ * Store the metadata object @variant; the provided @checksum is
+ * trusted.
*/
gboolean
ostree_repo_stage_metadata_trusted (OstreeRepo *self,
@@ -1075,6 +1113,13 @@ stage_metadata_thread (GSimpleAsyncResult *res,
/**
* ostree_repo_stage_metadata_async:
+ * @self: Repo
+ * @objtype: Object type
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Metadata
+ * @cancellable: Cancellable
+ * @callback: Invoked when metadata is staged
+ * @user_data: Data for @callback
*
* Asynchronously store the metadata object @variant. If provided,
* the checksum @expected_checksum will be verified.
@@ -1181,6 +1226,12 @@ _ostree_repo_get_uncompressed_object_cache_path (OstreeRepo *self,
/**
* ostree_repo_stage_content_trusted:
+ * @self: Repo
+ * @checksum: Store content using this ASCII SHA256 checksum
+ * @object_input: Content stream
+ * @length: Length of @object_input
+ * @cancellable: Cancellable
+ * @error: Data for @callback
*
* Store the content object streamed as @object_input, with total
* length @length. The given @checksum will be treated as trusted.
@@ -1203,6 +1254,13 @@ ostree_repo_stage_content_trusted (OstreeRepo *self,
/**
* ostree_repo_stage_content:
+ * @self: Repo
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object_input: Content object stream
+ * @length: Length of @object_input
+ * @out_csum: (out) (array fixed-size=32) (allow-none): Binary checksum
+ * @cancellable: Cancellable
+ * @error: Error
*
* Store the content object streamed as @object_input,
* with total length @length. The actual checksum will
@@ -1264,15 +1322,22 @@ stage_content_thread (GSimpleAsyncResult *res,
/**
* ostree_repo_stage_content_async:
+ * @self: Repo
+ * @expected_checksum: (allow-none): If provided, validate content against this checksum
+ * @object: Input
+ * @length: Length of @object
+ * @cancellable: Cancellable
+ * @callback: Invoked when content is staged
+ * @user_data: User data for @callback
*
- * Asynchronously store the content object @object. If provided,
- * the checksum @expected_checksum will be verified.
+ * Asynchronously store the content object @object. If provided, the
+ * checksum @expected_checksum will be verified.
*/
void
ostree_repo_stage_content_async (OstreeRepo *self,
const char *expected_checksum,
GInputStream *object,
- guint64 file_object_length,
+ guint64 length,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data)
@@ -1283,7 +1348,7 @@ ostree_repo_stage_content_async (OstreeRepo *self,
asyncdata->repo = g_object_ref (self);
asyncdata->expected_checksum = g_strdup (expected_checksum);
asyncdata->object = g_object_ref (object);
- asyncdata->file_object_length = file_object_length;
+ asyncdata->file_object_length = length;
asyncdata->cancellable = cancellable ? g_object_ref (cancellable) : NULL;
asyncdata->result = g_simple_async_result_new ((GObject*) self,
@@ -2268,6 +2333,11 @@ ostree_repo_load_variant_c (OstreeRepo *self,
/**
* ostree_repo_load_variant_if_exists:
+ * @self: Repo
+ * @objtype: Object type
+ * @sha256: ASCII checksum
+ * @out_variant: (out) (transfer full): Metadata
+ * @error: Error
*
* Attempt to load the metadata object @sha256 of type @objtype if it
* exists, storing the result in @out_variant. If it doesn't exist,
diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h
index e10e672..69494c9 100644
--- a/src/libostree/ostree-repo.h
+++ b/src/libostree/ostree-repo.h
@@ -41,6 +41,14 @@ gboolean ostree_repo_check (OstreeRepo *self, GError **error);
GFile * ostree_repo_get_path (OstreeRepo *self);
+/**
+ * OstreeRepoMode:
+ * @OSTREE_REPO_MODE_BARE: Files are stored as themselves; can only be written as root
+ * @OSTREE_REPO_MODE_ARCHIVE_Z2: Files are compressed, should be owned by non-root. Can be served via HTTP
+ *
+ * See the documentation of #OstreeRepo for more information about the
+ * possible modes.
+ */
typedef enum {
OSTREE_REPO_MODE_BARE,
OSTREE_REPO_MODE_ARCHIVE_Z2
@@ -115,8 +123,8 @@ gboolean ostree_repo_stage_metadata_finish (OstreeRepo *self,
gboolean ostree_repo_stage_content (OstreeRepo *self,
const char *expected_checksum,
- GInputStream *content,
- guint64 content_length,
+ GInputStream *object_input,
+ guint64 length,
guchar **out_csum,
GCancellable *cancellable,
GError **error);
@@ -124,21 +132,21 @@ gboolean ostree_repo_stage_content (OstreeRepo *self,
gboolean ostree_repo_stage_metadata_trusted (OstreeRepo *self,
OstreeObjectType objtype,
const char *checksum,
- GVariant *object,
+ GVariant *variant,
GCancellable *cancellable,
GError **error);
gboolean ostree_repo_stage_content_trusted (OstreeRepo *self,
const char *checksum,
- GInputStream *content,
- guint64 content_length,
+ GInputStream *object_input,
+ guint64 length,
GCancellable *cancellable,
GError **error);
void ostree_repo_stage_content_async (OstreeRepo *self,
const char *expected_checksum,
GInputStream *object,
- guint64 file_object_length,
+ guint64 length,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
@@ -184,7 +192,7 @@ gboolean ostree_repo_load_variant (OstreeRepo *self,
GError **error);
gboolean ostree_repo_load_variant_if_exists (OstreeRepo *self,
- OstreeObjectType expected_type,
+ OstreeObjectType objtype,
const char *sha256,
GVariant **out_variant,
GError **error);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
