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 <stdio.h>
00028 #include <ccn/ccn.h>
00029 #include "SyncMacros.h"
00030 
00031 struct SyncBaseStruct;  // defined in SyncBase.h
00032 
00033 typedef enum {
00034     SyncNodeKind_zero = 0,  /**< no bits set */
00035     SyncNodeKind_mark = 1   /**< mark bit (TBD) */
00036 } SyncNodeKind;
00037 
00038 typedef enum {
00039     SyncElemKind_node = 0,  /**< node */
00040     SyncElemKind_leaf = 1   /**< leaf */
00041 } SyncElemKind;
00042 
00043 struct SyncNodeElem {
00044     SyncElemKind kind;  /**< leaf/composite flag */
00045     ssize_t start;      /**< start of element encoding */
00046     ssize_t stop;       /**< stop of element encoding */
00047 };
00048 
00049 /**
00050  * A SyncLongHashStruct is used to accumulate a combined hash code
00051  * The pos field is the lowest index of a valid byte (bytes are accumulated
00052  * from high to low index).
00053  */
00054 struct SyncLongHashStruct {
00055     int pos;
00056     unsigned char bytes[MAX_HASH_BYTES];
00057 };
00058 
00059 /**
00060  * A SyncNodeComposite object holds the necessary data for a sync tree node.
00061  * It is the instantiated version, and there are routines for converting to
00062  * and from the ccnb encoded version, which has a very different format than
00063  * the type presented here.
00064  *
00065  * This type may be used while building a new node from components, and it may
00066  * be used for a node representation parsed from an external ccnb encoding.
00067  * 
00068  */
00069 struct SyncNodeComposite {
00070     struct SyncBaseStruct *base;
00071     SyncNodeKind kind;    /**< kind bits */
00072     int rc;               /**< reference count */
00073     int err;              /**< any error saved here */
00074     unsigned leafCount;   /**< leaf count (includes this node) */
00075     unsigned treeDepth;   /**< max tree depth (includes this node) */
00076     unsigned byteCount;   /**< byte count sum for child nodes (this node NOT included) */
00077     
00078     int refLen;           /**< number of references */
00079     int refLim;           /**< space allocated for references */
00080     struct SyncNodeElem *refs;    /**< pointer to references array */
00081     struct ccn_charbuf *cb;       /**< pointer to ccnb encoding */
00082     struct SyncLongHashStruct longHash;  /**< space for accumulated hash */
00083     struct ccn_charbuf *hash;     /**< combined hash (no tag, requires SyncEndComposite) */
00084     struct ccn_charbuf *minName;  /**< minimum name */
00085     struct ccn_charbuf *maxName;  /**< maximum name */
00086     struct ccn_charbuf *content;  /**< the signed content node (may be NULL) */
00087 };
00088 
00089 /**
00090  * Sets the error field when there is a processing error.
00091  */
00092 int
00093 SyncSetCompErr(struct SyncNodeComposite *nc, int val);
00094 
00095 /**
00096  * Tests the error field for an error returns 0 for no error != 0 for an error).
00097  */
00098 int
00099 SyncCheckCompErr(struct SyncNodeComposite *nc);
00100 
00101 /**
00102  * Makes a decoder from an offset range using the node charbuf.
00103  */
00104 struct ccn_buf_decoder *
00105 SyncInitDecoderFromOffset(struct ccn_buf_decoder *d,
00106                           struct SyncNodeComposite *nc,
00107                           ssize_t start, ssize_t stop);
00108 
00109 /**
00110  * Makes a decoder from an element.
00111  */
00112 struct ccn_buf_decoder *
00113 SyncInitDecoderFromElem(struct ccn_buf_decoder *d,
00114                         struct SyncNodeComposite *nc,
00115                         struct SyncNodeElem *ep);
00116 
00117 
00118 /**
00119  * Increments the reference count
00120  */
00121 void
00122 SyncNodeIncRC(struct SyncNodeComposite *nc);
00123 
00124 /**
00125  * Decrements the reference count
00126  * @returns nc if the resulting count is > 0.
00127  * @returns NULL if the resulting count == 0 (and frees the node).
00128  */
00129 struct SyncNodeComposite *
00130 SyncNodeDecRC(struct SyncNodeComposite *nc);
00131 
00132 
00133 ////////////////////////////////////////
00134 // Routines for comparison support
00135 ////////////////////////////////////////
00136 
00137 enum SyncCompareResult {
00138     SCR_before,
00139     SCR_min,
00140     SCR_inside,
00141     SCR_max,
00142     SCR_after,
00143     SCR_missing,
00144     SCR_error
00145 };
00146 
00147 /**
00148  * Compares a name against the min and max names in the node.
00149  */
00150 enum SyncCompareResult
00151 SyncNodeCompareMinMax(struct SyncNodeComposite *nc, struct ccn_charbuf *name);
00152 
00153 /**
00154  * Compares a name against the leaf in the element.
00155  */
00156 enum SyncCompareResult
00157 SyncNodeCompareLeaf(struct SyncNodeComposite *nc,
00158                     struct SyncNodeElem *ep,
00159                     struct ccn_charbuf *name);
00160 
00161 ////////////////////////////////////////
00162 // Routines for building CompositeNodes
00163 ////////////////////////////////////////
00164 
00165 /**
00166  * resets a composite node to its initial state
00167  * except that it retains any allocated storage
00168  */
00169 void
00170 SyncResetComposite(struct SyncNodeComposite *nc);
00171 
00172 /**
00173  * allocates a new, empty, composite object
00174  */
00175 struct SyncNodeComposite *
00176 SyncAllocComposite(struct SyncBaseStruct *base);
00177 
00178 /**
00179  * extends the references section of a composite object with a new offset pair
00180  * useful if NOT using SyncNodeAddName and SyncNodeAddNode
00181  */
00182 void
00183 SyncExtendComposite(struct SyncNodeComposite *nc,
00184                     SyncElemKind kind,
00185                     ssize_t start, ssize_t stop);
00186 
00187 /**
00188  * maintains the minName and maxName bounds
00189  * useful if NOT using SyncNodeAddName and SyncNodeAddNode
00190  */
00191 void
00192 SyncNodeMaintainMinMax(struct SyncNodeComposite *nc,
00193                        const struct ccn_charbuf *name);
00194 
00195 /**
00196  * extends the references section of a composite object with a new name,
00197  * updating the composite fields (including the name bounds)
00198  * the names MUST be added in sorted order!
00199  */
00200 void
00201 SyncNodeAddName(struct SyncNodeComposite *nc,
00202                 const struct ccn_charbuf *name);
00203 
00204 /**
00205  * extends the references section of a composite object with a new node,
00206  * updating the composite fields (including the name bounds)
00207  * the nodes MUST be added in sorted order!
00208  */
00209 void
00210 SyncNodeAddNode(struct SyncNodeComposite *nc,
00211                 struct SyncNodeComposite *node);
00212 
00213 /**
00214  * appends the ccnb encoding for the long hash of nc to cb
00215  */
00216 int
00217 SyncNodeAppendLongHash(struct ccn_charbuf *cb, struct SyncNodeComposite *nc);
00218 
00219 /**
00220  * endComposite finishes up the encoding, appending the composite fields
00221  * the hash field will be valid after this call
00222  */
00223 void
00224 SyncEndComposite(struct SyncNodeComposite *nc);
00225 
00226 /**
00227  * freeComposite returns the storage for the composite object
00228  */
00229 void
00230 SyncFreeComposite(struct SyncNodeComposite *nc);
00231 
00232 /**
00233  * writes the encoding to a file
00234  * (primarily useful for test and debug code)
00235  */
00236 void
00237 SyncWriteComposite(struct SyncNodeComposite *nc, FILE *f);
00238 
00239 /**
00240  * parses an encoded node and fills in the supplied node
00241  * implicitly resets the node at the start of the parse
00242  * @returns nc->err
00243  */
00244 int
00245 SyncParseComposite(struct SyncNodeComposite *nc, struct ccn_buf_decoder *d);
00246 
00247 
00248 #endif
Generated on Tue Aug 21 14:54:19 2012 for Content-Centric Networking in C by  doxygen 1.6.3