From 35d7b9cdbf908527232bf0fcc0238b6d1f26edc3 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Sat, 17 Aug 2013 13:57:22 -0400 Subject: [PATCH] libostree: Increase gtk-doc coverage of ostree-repo.[ch] --- src/libostree/ostree-repo-pull.c | 8 +-- src/libostree/ostree-repo.c | 105 ++++++++++++++++++++++++++++++- src/libostree/ostree-repo.h | 58 +++++++++++++++-- 3 files changed, 160 insertions(+), 11 deletions(-) diff --git a/src/libostree/ostree-repo-pull.c b/src/libostree/ostree-repo-pull.c index 218f1a3f..14adeca7 100644 --- a/src/libostree/ostree-repo-pull.c +++ b/src/libostree/ostree-repo-pull.c @@ -1161,7 +1161,7 @@ load_remote_repo_config (OtPullData *pull_data, } gboolean -ostree_repo_pull (OstreeRepo *repo, +ostree_repo_pull (OstreeRepo *self, const char *remote_name, char **refs_to_fetch, OstreeRepoPullFlags flags, @@ -1201,7 +1201,7 @@ ostree_repo_pull (OstreeRepo *repo, pull_data->loop = g_main_loop_new (pull_data->main_context, FALSE); pull_data->flags = flags; - pull_data->repo = repo; + pull_data->repo = self; pull_data->scanned_metadata = g_hash_table_new_full (ostree_hash_object_name, g_variant_equal, (GDestroyNotify)g_variant_unref, NULL); @@ -1213,10 +1213,10 @@ ostree_repo_pull (OstreeRepo *repo, start_time = g_get_monotonic_time (); pull_data->remote_name = g_strdup (remote_name); - config = ostree_repo_get_config (repo); + config = ostree_repo_get_config (self); remote_key = g_strdup_printf ("remote \"%s\"", pull_data->remote_name); - if (!repo_get_string_key_inherit (repo, remote_key, "url", &baseurl, error)) + if (!repo_get_string_key_inherit (self, remote_key, "url", &baseurl, error)) goto out; pull_data->base_uri = soup_uri_new (baseurl); diff --git a/src/libostree/ostree-repo.c b/src/libostree/ostree-repo.c index c7ff2aa4..a77a5025 100644 --- a/src/libostree/ostree-repo.c +++ b/src/libostree/ostree-repo.c @@ -1397,6 +1397,22 @@ create_empty_gvariant_dict (void) return g_variant_builder_end (&builder); } +/** + * ostree_repo_stage_commit: + * @self: Repo + * @branch: Name of ref + * @parent: (allow-none): ASCII SHA256 checksum for parent, or %NULL for none + * @subject: Subject + * @body: Body + * @root_contents_checksum: ASCII SHA256 checksum for %OSTREE_OBJECT_TYPE_DIR_TREE + * @root_metadata_checksum: ASCII SHA256 checksum for %OSTREE_OBJECT_TYPE_DIR_META + * @out_commit: (out): Resulting ASCII SHA256 checksum for commit + * @cancellable: Cancellable + * @error: Error + * + * Write a commit metadata object, referencing @root_contents_checksum + * and @root_metadata_checksum. + */ gboolean ostree_repo_stage_commit (OstreeRepo *self, const char *branch, @@ -1778,6 +1794,18 @@ ostree_repo_stage_directory_to_mtree (OstreeRepo *self, return ret; } +/** + * ostree_repo_stage_mtree: + * @self: Repo + * @mtree: Mutable tree + * @out_contents_checksum: (out): Return location for ASCII checksum + * @cancellable: Cancellable + * @error: Error + * + * Write all metadata objects for @mtree to repo; the resulting + * @out_contents_checksum contains the checksum for the + * %OSTREE_OBJECT_TYPE_DIR_TREE object. + */ gboolean ostree_repo_stage_mtree (OstreeRepo *self, OstreeMutableTree *mtree, @@ -2058,6 +2086,19 @@ load_metadata_internal (OstreeRepo *self, return ret; } +/** + * ostree_repo_load_file: + * @self: Repo + * @checksum: ASCII SHA256 checksum + * @out_input: (out) (allow-none): File content + * @out_file_info: (out) (allow-none): File information + * @out_xattrs: (out) (allow-none): Extended attributes + * @cancellable: Cancellable + * @error: Error + * + * Load content object, decomposing it into three parts: the actual + * content (for regular files), the metadata, and extended attributes. + */ gboolean ostree_repo_load_file (OstreeRepo *self, const char *checksum, @@ -2147,6 +2188,19 @@ ostree_repo_load_file (OstreeRepo *self, return ret; } +/** + * ostree_repo_load_object_stream: + * @self: Repo + * @objtype: Object type + * @checksum: ASCII SHA256 checksum + * @out_input: (out): Stream for object + * @out_size: (out): Length of @out_input + * @cancellable: Cancellable + * @error: Error + * + * Load object as a stream; useful when copying objects between + * repositories. + */ gboolean ostree_repo_load_object_stream (OstreeRepo *self, OstreeObjectType objtype, @@ -2222,6 +2276,20 @@ out: return ret; } +/** + * ostree_repo_has_object: + * @self: Repo + * @objtype: Object type + * @checksum: ASCII SHA256 checksum + * @out_have_object: (out): %TRUE if repository contains object + * @cancellable: Cancellable + * @error: Error + * + * Set @out_have_object to %TRUE if @self contains the given object; + * %FALSE otherwise. + * + * Returns: %FALSE if an unexpected error occurred, %TRUE otherwise + */ gboolean ostree_repo_has_object (OstreeRepo *self, OstreeObjectType objtype, @@ -2311,6 +2379,17 @@ ostree_repo_query_object_storage_size (OstreeRepo *self, return ret; } +/** + * ostree_repo_load_variant_c: + * @self: Repo + * @objtype: Expected object type + * @csum: Binary checksum + * @out_variant: (out): (transfer full): Metadata object + * @error: Error + * + * Load the metadata object @csum of type @objtype, storing the + * result in @out_variant. + */ gboolean ostree_repo_load_variant_c (OstreeRepo *self, OstreeObjectType objtype, @@ -2433,6 +2512,16 @@ ostree_repo_list_objects (OstreeRepo *self, return ret; } +/** + * ostree_repo_read_commit: + * @self: Repo + * @rev: Revision (ref or ASCII checksum) + * @out_root: (out): An #OstreeRepoFile corresponding to the root + * @cancellable: Cancellable + * @error: Error + * + * Load the content for @rev into @out_root. + */ gboolean ostree_repo_read_commit (OstreeRepo *self, const char *rev, @@ -2458,8 +2547,22 @@ ostree_repo_read_commit (OstreeRepo *self, } #ifndef HAVE_LIBSOUP +/** + * ostree_repo_pull: + * @self: Repo + * @remote_name: Name of remote + * @refs_to_fetch: (array zero-terminated=1) (element-type utf8) (allow-none): Optional list of refs; if %NULL, fetch all configured refs + * @flags: Options controlling fetch behavior + * @cancellable: Cancellable + * @error: Error + * + * Connect to the remote repository, fetching the specified set of + * refs @refs_to_fetch. For each ref that is changed, download the + * commit, all metadata, and all content objects, storing them safely + * on disk in @self. + */ gboolean -ostree_repo_pull (OstreeRepo *repo, +ostree_repo_pull (OstreeRepo *self, const char *remote_name, char **refs_to_fetch, OstreeRepoPullFlags flags, diff --git a/src/libostree/ostree-repo.h b/src/libostree/ostree-repo.h index 69494c99..102fbf51 100644 --- a/src/libostree/ostree-repo.h +++ b/src/libostree/ostree-repo.h @@ -180,7 +180,7 @@ gboolean ostree_repo_list_refs (OstreeRepo *repo, GError **error); gboolean ostree_repo_load_variant_c (OstreeRepo *self, - OstreeObjectType expected_type, + OstreeObjectType objtype, const guchar *csum, GVariant **out_variant, GError **error); @@ -198,7 +198,7 @@ gboolean ostree_repo_load_variant_if_exists (OstreeRepo *self, GError **error); gboolean ostree_repo_load_file (OstreeRepo *self, - const char *entry_sha256, + const char *checksum, GInputStream **out_input, GFileInfo **out_file_info, GVariant **out_xattrs, @@ -226,16 +226,35 @@ gboolean ostree_repo_delete_object (OstreeRepo *self, GCancellable *cancellable, GError **error); +/** + * OstreeRepoCommitFilterResult: + * @OSTREE_REPO_COMMIT_FILTER_ALLOW: Do commit this object + * @OSTREE_REPO_COMMIT_FILTER_SKIP: Ignore this object + */ typedef enum { OSTREE_REPO_COMMIT_FILTER_ALLOW, OSTREE_REPO_COMMIT_FILTER_SKIP } OstreeRepoCommitFilterResult; +/** + * OstreeRepoCommitFilter: + * @repo: Repo + * @path: Path to file + * @file_info: File information + * @user_data: User data + * + * Returns: #OstreeRepoCommitFilterResult saying whether or not to commit this file + */ typedef OstreeRepoCommitFilterResult (*OstreeRepoCommitFilter) (OstreeRepo *repo, const char *path, GFileInfo *file_info, gpointer user_data); +/** + * OstreeRepoCommitModifier: + * + * A structure allowing control over commits. + */ typedef struct { volatile gint refcount; @@ -271,7 +290,7 @@ gboolean ostree_repo_stage_archive_to_mtree (OstreeRepo * GError **error); gboolean ostree_repo_stage_mtree (OstreeRepo *self, - OstreeMutableTree *tree, + OstreeMutableTree *mtree, char **out_contents_checksum, GCancellable *cancellable, GError **error); @@ -281,17 +300,27 @@ gboolean ostree_repo_stage_commit (OstreeRepo *self, const char *parent, const char *subject, const char *body, - const char *content_checksum, - const char *metadata_checksum, + const char *root_contents_checksum, + const char *root_metadata_checksum, char **out_commit, GCancellable *cancellable, GError **error); +/** + * OstreeRepoCheckoutMode: + * @OSTREE_REPO_CHECKOUT_MODE_NONE: No special options + * @OSTREE_REPO_CHECKOUT_MODE_USER: Ignore uid/gid of files + */ typedef enum { OSTREE_REPO_CHECKOUT_MODE_NONE = 0, OSTREE_REPO_CHECKOUT_MODE_USER = 1 } OstreeRepoCheckoutMode; +/** + * OstreeRepoCheckoutOverwriteMode: + * @OSTREE_REPO_CHECKOUT_OVERWRITE_NONE: No special options + * @OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES: When layering checkouts, overwrite earlier files, but keep earlier directories + */ typedef enum { OSTREE_REPO_CHECKOUT_OVERWRITE_NONE = 0, OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES = 1 @@ -323,6 +352,12 @@ gboolean ostree_repo_read_commit (OstreeRepo *self, GCancellable *cancellable, GError **error); +/** + * OstreeRepoListObjectsFlags: + * @OSTREE_REPO_LIST_OBJECTS_LOOSE: List only loose (plain file) objects + * @OSTREE_REPO_LIST_OBJECTS_PACKED: List only packed (compacted into blobs) objects + * @OSTREE_REPO_LIST_OBJECTS_ALL: List all objects + */ typedef enum { OSTREE_REPO_LIST_OBJECTS_LOOSE = (1 << 0), OSTREE_REPO_LIST_OBJECTS_PACKED = (1 << 1), @@ -358,6 +393,12 @@ gboolean ostree_repo_traverse_commit (OstreeRepo *repo, GCancellable *cancellable, GError **error); +/** + * OstreeRepoPruneFlags: + * @OSTREE_REPO_PRUNE_FLAGS_NONE: No special options for pruning + * @OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE: Don't actually delete objects + * @OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY: Do not traverse individual commit objects, only follow refs + */ typedef enum { OSTREE_REPO_PRUNE_FLAGS_NONE, OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE, @@ -373,12 +414,17 @@ gboolean ostree_repo_prune (OstreeRepo *repo, GCancellable *cancellable, GError **error); +/** + * OstreeRepoPullFlags: + * @OSTREE_REPO_PULL_FLAGS_NONE: No special options for pull + * @OSTREE_REPO_PULL_FLAGS_RELATED: Fetch objects referred to by each commit + */ typedef enum { OSTREE_REPO_PULL_FLAGS_NONE, OSTREE_REPO_PULL_FLAGS_RELATED } OstreeRepoPullFlags; -gboolean ostree_repo_pull (OstreeRepo *repo, +gboolean ostree_repo_pull (OstreeRepo *self, const char *remote_name, char **refs_to_fetch, OstreeRepoPullFlags flags,