lib/checkout: add filter API to skip over files

This is analogous to the filtering support for the commit API: we allow
library users to skip over checking out specific files. This is useful
in some tricky situations where we *know* that the files to be checked
out will conflict with existing files in subtle ways.

One such example is in rpm-ostree support for multilib. There, we want
to allow checking out a package onto an existing tree, but skipping over
files that are not coloured to our preferred value (e.g. not overwriting
an i686 version of `ldconfig` if we already have the `x86_64` version).
See https://github.com/projectatomic/rpm-ostree/pull/1227 for details.

Closes: #1441
Approved by: cgwalters

src/libostree/ostree-repo.h

@@ -942,6 +942,34 @@ ostree_repo_checkout_tree (OstreeRepo               *self,
                            GCancellable             *cancellable,
                            GError                  **error);
 
+/**
+ * OstreeRepoCheckoutFilterResult:
+ * @OSTREE_REPO_CHECKOUT_FILTER_ALLOW: Do checkout this object
+ * @OSTREE_REPO_CHECKOUT_FILTER_SKIP: Ignore this object
+ *
+ * Since: 2018.2
+ */
+typedef enum {
+  OSTREE_REPO_CHECKOUT_FILTER_ALLOW,
+  OSTREE_REPO_CHECKOUT_FILTER_SKIP
+} OstreeRepoCheckoutFilterResult;
+
+/**
+ * OstreeRepoCheckoutFilter:
+ * @repo: Repo
+ * @path: Path to file
+ * @stbuf: File information
+ * @user_data: User data
+ *
+ * Returns: #OstreeRepoCheckoutFilterResult saying whether or not to checkout this file
+ *
+ * Since: 2018.2
+ */
+typedef OstreeRepoCheckoutFilterResult (*OstreeRepoCheckoutFilter) (OstreeRepo    *repo,
+                                                                    const char    *path,
+                                                                    struct stat   *stbuf,
+                                                                    gpointer       user_data);
+
 /**
  * OstreeRepoCheckoutAtOptions:
  *
@@ -969,7 +997,9 @@ typedef struct {
   OstreeRepoDevInoCache *devino_to_csum_cache;
 
   int unused_ints[6];
-  gpointer unused_ptrs[5];
+  gpointer unused_ptrs[3];
+  OstreeRepoCheckoutFilter filter; /* Since: 2018.2 */
+  gpointer filter_user_data; /* Since: 2018.2 */
   OstreeSePolicy *sepolicy; /* Since: 2017.6 */
   const char *sepolicy_prefix;
 } OstreeRepoCheckoutAtOptions;