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