SyncRoot.h

Go to the documentation of this file.
00001 /**
00002  * @file sync/SyncRoot.h
00003  *  
00004  * Part of CCNx Sync.
00005  */
00006 /*
00007  * Copyright (C) 2011-2012 Palo Alto Research Center, Inc.
00008  *
00009  * This library is free software; you can redistribute it and/or modify it
00010  * under the terms of the GNU Lesser General Public License version 2.1
00011  * as published by the Free Software Foundation.
00012  * This library is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00015  * Lesser General Public License for more details. You should have received
00016  * a copy of the GNU Lesser General Public License along with this library;
00017  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00018  * Fifth Floor, Boston, MA 02110-1301 USA.
00019  */
00020 
00021 #ifndef CCN_SyncRoot
00022 #define CCN_SyncRoot
00023 
00024 #include <ccn/ccn.h>
00025 
00026 struct SyncHashCacheHead;  // defined in SyncHashCache.h
00027 struct SyncNameAccum;      // defined in SyncUtil.h
00028 struct SyncActionData;     // defined in SyncActions.h
00029 struct SyncCompareData;    // defined in SyncActions.c
00030 struct SyncUpdateData;     // defined in SyncActions.c
00031 struct SyncBaseStruct;     // defined in SyncBase.h
00032 struct SyncRootPrivate;    // private to SyncRoot.c
00033 
00034 /**
00035  * A SyncRootStruct object holds the necessary data for a root sync tree.
00036  */
00037 struct SyncRootStruct {
00038     unsigned rootId;                      /**< root Id for reporting */
00039     struct SyncBaseStruct *base;          /**< Sync Agent base */
00040     struct SyncRootStruct *next;          /**< next root in our list */
00041     struct SyncRootPrivate *priv;         /**< private to SyncRoot */
00042     struct SyncHashCacheHead *ch;         /**< cache head */
00043     struct ccn_charbuf *topoPrefix;       /**< Sync Protocol topo prefix */
00044     struct ccn_charbuf *namingPrefix;     /**< Sync Protocol naming prefix */
00045     struct SyncNameAccum *filter;         /**< filter clauses */
00046     struct ccn_charbuf *currentHash;      /**< current top-level cache hash */
00047     struct SyncNameAccum *namesToAdd;     /**< names needing addition to root */
00048     struct SyncNameAccum *namesToFetch;   /**< names needing contents fetch */
00049     struct SyncActionData *actions;       /**< data for pending interests */
00050     struct SyncCompareData *compare;      /**< data for doing sync tree comparison */
00051     struct SyncUpdateData *update;        /**< data for doing sync tree updates */
00052     struct ccn_charbuf *sliceCoding;      /**< ccnb encoding for the description */
00053     struct ccn_charbuf *sliceHash;        /**< the raw hash of the sliceCoding */
00054 };
00055 
00056 /**
00057  * namesToAdd has the names where content is known to be present.  These names
00058  * should come from SyncNotifyContent.
00059  * The name storage belongs to the root.
00060  *
00061  * namesToFetch has the names where content should be fetched.  Once content is
00062  * fetched and stored to the repo the names should be appended to namesToAdd.
00063  * The name storage belongs to the root.
00064  */
00065 
00066 ///////////////////////////////////////////////////////
00067 // Routines for working with sync tree roots
00068 ///////////////////////////////////////////////////////
00069 
00070 /**
00071  * Creates a new root structure and adds it to the base.
00072  * The syncScope will be used for sync control interests (-1 for unscoped).
00073  * The topoPrefix and namingPrefix will be copied and canonicalized.
00074  * The filter (and the names in it) will also be copied and canonicalized.
00075  * Canonicalized data is owned by the base.
00076  * @returns the new root object
00077  */
00078 struct SyncRootStruct *
00079 SyncAddRoot(struct SyncBaseStruct *base,
00080             int syncScope,
00081             const struct ccn_charbuf *topoPrefix,
00082             const struct ccn_charbuf *namingPrefix,
00083             struct SyncNameAccum *filter);
00084 
00085 /**
00086  * Removes the root from the base, and frees up associated storage.
00087  * Requires that there are no active comparisons.
00088  * Deactivates all pending interests.
00089  * @returns NULL if the root was removed, the root itself if not removed.
00090  */
00091 struct SyncRootStruct *
00092 SyncRemRoot(struct SyncRootStruct *root);
00093 
00094 /**
00095  * Parse a content object representing a config slice,
00096  * and if successful add it to the base.
00097  * @returns the new root if successful, NULL otherwise.
00098  */
00099 struct SyncRootStruct *
00100 SyncRootDecodeAndAdd(struct SyncBaseStruct *base,
00101                      struct ccn_buf_decoder *d);
00102 
00103 /**
00104  * Appends the ccnb encoding for a config slice to the provided cb.
00105  * @returns -1 for failure, 0 for success.
00106  */
00107 int
00108 SyncRootAppendSlice(struct ccn_charbuf *cd, struct SyncRootStruct *root);
00109 
00110 enum SyncRootLookupCode {
00111     SyncRootLookupCode_none,        /**< not covered by this root */
00112     SyncRootLookupCode_covered,     /**< covered by this root */
00113     SyncRootLookupCode_error        /**< error in the name or the state */
00114 };
00115     
00116 /**
00117  * @returns the top entry, if the root hash has been established for this root,
00118  * otherwise returns NULL.
00119  */
00120 struct SyncHashCacheEntry *
00121 SyncRootTopEntry(struct SyncRootStruct *root);
00122 
00123 /**
00124  * Tests to see if the name is covered by this root.
00125  * Useful for testing full names given by the Repo.
00126  * The topoPrefix does not participate, but the filter does.
00127  * @returns a code indicating the result
00128  */
00129 enum SyncRootLookupCode
00130 SyncRootLookupName(struct SyncRootStruct *root,
00131                     const struct ccn_charbuf *name);
00132 
00133 #endif
Generated on Tue Aug 21 14:54:19 2012 for Content-Centric Networking in C by  doxygen 1.6.3