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