SyncNode.h

Go to the documentation of this file.
00001 /**
00002  * @file sync/SyncNode.h
00003  *  
00004  * Part of CCNx Sync.
00005  *
00006  * Copyright (C) 2011 Palo Alto Research Center, Inc.
00007  *
00008  * This library is free software; you can redistribute it and/or modify it
00009  * under the terms of the GNU Lesser General Public License version 2.1
00010  * as published by the Free Software Foundation.
00011  * This library is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00014  * Lesser General Public License for more details. You should have received
00015  * a copy of the GNU Lesser General Public License along with this library;
00016  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00017  * Fifth Floor, Boston, MA 02110-1301 USA.
00018  */
00019 
00020 /**
00021  * SyncNode is the basic support for node objects in Sync.
00022  */
00023 
00024 #ifndef CCN_SyncNode
00025 #define CCN_SyncNode
00026 
00027 #include "SyncBase.h"
00028 
00029 typedef enum {
00030     SyncNodeKind_zero = 0,  /**< no bits set */
00031     SyncNodeKind_mark = 1   /**< mark bit (TBD) */
00032 } SyncNodeKind;
00033 
00034 typedef enum {
00035     SyncElemKind_node = 0,  /**< node */
00036     SyncElemKind_leaf = 1   /**< leaf */
00037 } SyncElemKind;
00038 
00039 struct SyncNodeElem {
00040     SyncElemKind kind;  /**< leaf/composite flag */
00041     ssize_t start;      /**< start of element encoding */
00042     ssize_t stop;       /**< stop of element encoding */
00043 };
00044 
00045 /**
00046  * A SyncLongHashStruct is used to accumulate a combined hash code
00047  * The pos field is the lowest index of a valid byte (bytes are accumulated
00048  * from high to low index).
00049  */
00050 struct SyncLongHashStruct {
00051     int pos;
00052     unsigned char bytes[MAX_HASH_BYTES];
00053 };
00054 
00055 /**
00056  * A SyncNodeComposite object holds the necessary data for a sync tree node.
00057  * It is the instantiated version, and there are routines for converting to
00058  * and from the ccnb encoded version, which has a very different format than
00059  * the type presented here.
00060  *
00061  * This type may be used while building a new node from components, and it may
00062  * be used for a node representation parsed from an external ccnb encoding.
00063  * 
00064  */
00065 struct SyncNodeComposite {
00066     struct SyncBaseStruct *base;
00067     SyncNodeKind kind;    /**< kind bits */
00068     int rc;               /**< reference count */
00069     int err;              /**< any error saved here */
00070     unsigned leafCount;   /**< leaf count (includes this node) */
00071     unsigned treeDepth;   /**< max tree depth (includes this node) */
00072     unsigned byteCount;   /**< byte count sum for child nodes (this node NOT included) */
00073     
00074     int refLen;           /**< number of references */
00075     int refLim;           /**< space allocated for references */
00076     struct SyncNodeElem *refs;    /**< pointer to references array */
00077     struct ccn_charbuf *cb;       /**< pointer to ccnb encoding */
00078     struct SyncLongHashStruct longHash;  /**< space for accumulated hash */
00079     struct ccn_charbuf *hash;     /**< combined hash (no tag, requires SyncEndComposite) */
00080     struct ccn_charbuf *minName;  /**< minimum name */
00081     struct ccn_charbuf *maxName;  /**< maximum name */
00082     struct ccn_charbuf *content;  /**< the signed content node (may be NULL) */
00083 };
00084 
00085 /**
00086  * Sets the error field when there is a processing error.
00087  */
00088 int
00089 SyncSetCompErr(struct SyncNodeComposite *nc, int val);
00090 
00091 /**
00092  * Tests the error field for an error returns 0 for no error != 0 for an error).
00093  */
00094 int
00095 SyncCheckCompErr(struct SyncNodeComposite *nc);
00096 
00097 /**
00098  * Makes a decoder from an offset range using the node charbuf.
00099  */
00100 struct ccn_buf_decoder *
00101 SyncInitDecoderFromOffset(struct ccn_buf_decoder *d,
00102                           struct SyncNodeComposite *nc,
00103                           ssize_t start, ssize_t stop);
00104 
00105 /**
00106  * Makes a decoder from an element.
00107  */
00108 struct ccn_buf_decoder *
00109 SyncInitDecoderFromElem(struct ccn_buf_decoder *d,
00110                         struct SyncNodeComposite *nc,
00111                         struct SyncNodeElem *ep);
00112 
00113 
00114 /**
00115  * Increments the reference count
00116  */
00117 void
00118 SyncNodeIncRC(struct SyncNodeComposite *nc);
00119 
00120 /**
00121  * Decrements the reference count
00122  * @returns nc if the resulting count is > 0.
00123  * @returns NULL if the resulting count == 0 (and frees the node).
00124  */
00125 struct SyncNodeComposite *
00126 SyncNodeDecRC(struct SyncNodeComposite *nc);
00127 
00128 
00129 ////////////////////////////////////////
00130 // Routines for comparison support
00131 ////////////////////////////////////////
00132 
00133 enum SyncCompareResult {
00134     SCR_before,
00135     SCR_min,
00136     SCR_inside,
00137     SCR_max,
00138     SCR_after,
00139     SCR_missing,
00140     SCR_error
00141 };
00142 
00143 /**
00144  * Compares a name against the min and max names in the node.
00145  */
00146 enum SyncCompareResult
00147 SyncNodeCompareMinMax(struct SyncNodeComposite *nc, struct ccn_charbuf *name);
00148 
00149 /**
00150  * Compares a name against the leaf in the element.
00151  */
00152 enum SyncCompareResult
00153 SyncNodeCompareLeaf(struct SyncNodeComposite *nc,
00154                     struct SyncNodeElem *ep,
00155                     struct ccn_charbuf *name);
00156 
00157 ////////////////////////////////////////
00158 // Routines for building CompositeNodes
00159 ////////////////////////////////////////
00160 
00161 /**
00162  * resets a composite node to its initial state
00163  * except that it retains any allocated storage
00164  */
00165 void
00166 SyncResetComposite(struct SyncNodeComposite *nc);
00167 
00168 /**
00169  * allocates a new, empty, composite object
00170  */
00171 struct SyncNodeComposite *
00172 SyncAllocComposite(struct SyncBaseStruct *base);
00173 
00174 /**
00175  * extends the references section of a composite object with a new offset pair
00176  * useful if NOT using SyncNodeAddName and SyncNodeAddNode
00177  */
00178 void
00179 SyncExtendComposite(struct SyncNodeComposite *nc,
00180                     SyncElemKind kind,
00181                     ssize_t start, ssize_t stop);
00182 
00183 /**
00184  * maintains the minName and maxName bounds
00185  * useful if NOT using SyncNodeAddName and SyncNodeAddNode
00186  */
00187 void
00188 SyncNodeMaintainMinMax(struct SyncNodeComposite *nc,
00189                        const struct ccn_charbuf *name);
00190 
00191 /**
00192  * extends the references section of a composite object with a new name,
00193  * updating the composite fields (including the name bounds)
00194  * the names MUST be added in sorted order!
00195  */
00196 void
00197 SyncNodeAddName(struct SyncNodeComposite *nc,
00198                 const struct ccn_charbuf *name);
00199 
00200 /**
00201  * extends the references section of a composite object with a new node,
00202  * updating the composite fields (including the name bounds)
00203  * the nodes MUST be added in sorted order!
00204  */
00205 void
00206 SyncNodeAddNode(struct SyncNodeComposite *nc,
00207                 struct SyncNodeComposite *node);
00208 
00209 /**
00210  * appends the ccnb encoding for the long hash of nc to cb
00211  */
00212 int
00213 SyncNodeAppendLongHash(struct ccn_charbuf *cb, struct SyncNodeComposite *nc);
00214 
00215 /**
00216  * endComposite finishes up the encoding, appending the composite fields
00217  * the hash field will be valid after this call
00218  */
00219 void
00220 SyncEndComposite(struct SyncNodeComposite *nc);
00221 
00222 /**
00223  * freeComposite returns the storage for the composite object
00224  */
00225 void
00226 SyncFreeComposite(struct SyncNodeComposite *nc);
00227 
00228 /**
00229  * writes the encoding to a file
00230  * (primarily useful for test and debug code)
00231  */
00232 void
00233 SyncWriteComposite(struct SyncNodeComposite *nc, FILE *f);
00234 
00235 /**
00236  * parses an encoded node and fills in the supplied node
00237  * implicitly resets the node at the start of the parse
00238  * @returns nc->err
00239  */
00240 int
00241 SyncParseComposite(struct SyncNodeComposite *nc, struct ccn_buf_decoder *d);
00242 
00243 
00244 #endif

Generated on Thu Feb 16 00:44:01 2012 for Content-Centric Networking in C by  doxygen 1.5.6