SyncUtil.h

Go to the documentation of this file.
00001 /**
00002  * @file sync/SyncUtil.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 #ifndef CCN_SyncUtil
00021 #define CCN_SyncUtil
00022 
00023 #include "IndexSorter.h"
00024 #include <ccn/ccn.h>
00025 
00026 struct SyncLongHashStruct;
00027 struct SyncRootStruct;
00028 struct SyncBaseStruct;
00029 
00030 // emit a message to stderr
00031 void
00032 SyncNoteErr(const char *msg);
00033 
00034 int
00035 SyncSetDecodeErr(struct ccn_buf_decoder *d, int val);
00036 
00037 int
00038 SyncCheckDecodeErr(struct ccn_buf_decoder *d);
00039 
00040 
00041 //// Elapsed high-precision time
00042 
00043 // get current time in microseconds (since arbitrary event)
00044 int64_t
00045 SyncCurrentTime(void);
00046 
00047 // get delta time in microseconds (from mt1 to mt2)
00048 int64_t
00049 SyncDeltaTime(int64_t mt1, int64_t mt2);
00050 
00051 // Some basic ccn_charbuf utilities
00052 
00053 struct ccn_buf_decoder *
00054 SyncInitDecoderFromCharbufRange(struct ccn_buf_decoder *d,
00055                                 const struct ccn_charbuf *cb,
00056                                 ssize_t start, ssize_t stop);
00057 
00058 struct ccn_buf_decoder *
00059 SyncInitDecoderFromCharbuf(struct ccn_buf_decoder *d,
00060                            const struct ccn_charbuf *cb,
00061                            ssize_t start);
00062 
00063 // for a hex encoding character, returns a a 4-bit unsigned number
00064 // otherwise returns -1
00065 int
00066 SyncDecodeHexDigit(char c);
00067 
00068 // for a valid URI character, returns the code for the character
00069 // otherwise returns -1
00070 int
00071 SyncDecodeUriChar(char c);
00072 
00073 char *
00074 SyncHexStr(const unsigned char *cp, size_t sz);
00075 
00076 /////////////////////////////////////////////////////////////////
00077 // Routines for root-relative reporting.
00078 /////////////////////////////////////////////////////////////////
00079 
00080 int
00081 SyncNoteFailed(struct SyncRootStruct *root, char *where, char *why, int line);
00082 
00083 void
00084 SyncNoteSimple(struct SyncRootStruct *root, char *where, char *s1);
00085 
00086 void
00087 SyncNoteSimple2(struct SyncRootStruct *root, char *where, char *s1, char *s2);
00088 
00089 void
00090 SyncNoteSimple3(struct SyncRootStruct *root, char *where, char *s1, char *s2, char *s3);
00091 
00092 void
00093 SyncNoteUri(struct SyncRootStruct *root, char *where, char *why, struct ccn_charbuf *name);
00094 
00095 void
00096 SyncNoteUriBase(struct SyncBaseStruct *base, char *where, char *why, struct ccn_charbuf *name);
00097 
00098 /////////////////////////////////////////////////////////////////
00099 // Routines for dealing with names.
00100 /////////////////////////////////////////////////////////////////
00101 
00102 /**
00103  * compare two names
00104  * advances both decoders, but early exit may leave them not fully over the names
00105  * decoder error flags may be useful, though, if any errors occur
00106  */
00107 int
00108 SyncCmpNamesInner(struct ccn_buf_decoder *xx, struct ccn_buf_decoder *yy);
00109 
00110 /**
00111  * compare two names
00112  * @returns >1 if cbx > cby, 0 if cby == cby, <-1 if cbx < cby
00113  * @returns BAD_CMP for a parsing error
00114  */
00115 #define SYNC_BAD_CMP (-2)
00116 int
00117 SyncCmpNames(const struct ccn_charbuf *cbx, const struct ccn_charbuf *cby);
00118 
00119 /**
00120  * tests to see if charbuf refers to a name
00121  * @returns 1 for a name, 0 otherwise
00122  */
00123 int
00124 SyncIsName(const struct ccn_charbuf *cb);
00125 
00126 /**
00127  * @returns number of components in the name
00128  */
00129 int
00130 SyncComponentCount(const struct ccn_charbuf *name);
00131 
00132 /**
00133  * simple pattern matching, where the pattern may contain components with
00134  * a single 255 byte to match a single name component
00135  * @returns number of matching components in the pattern if the name
00136  * (starting at component index start) matches the prefix,
00137  * @returns -1 if there is a parsing error or no match
00138  */
00139 int
00140 SyncPatternMatch(const struct ccn_charbuf *pattern,
00141                  const struct ccn_charbuf *name,
00142                  int start);
00143 
00144 /**
00145  * @returns number of components in the prefix if the name
00146  * (starting at component index start) matches the prefix,
00147  * @returns -1 if there is a parsing error or no match
00148  */
00149 int
00150 SyncPrefixMatch(const struct ccn_charbuf *prefix,
00151                 const struct ccn_charbuf *name,
00152                 int start);
00153 
00154 /**
00155  * @returns number of components in the longest prefix of both x and y
00156  * @returns -1 if there is a parsing error
00157  */
00158 int
00159 SyncComponentMatch(const struct ccn_charbuf *x,
00160                    const struct ccn_charbuf *y);
00161 
00162 /**
00163  * finds the bytes for a component (not including the tag)
00164  * src must be a name, comp the component index
00165  * @returns < 0 for an error, 0 otherwise
00166  */
00167 int
00168 SyncGetComponentPtr(const struct ccn_charbuf *src, int comp,
00169                     const unsigned char **xp, ssize_t *xs);
00170 
00171 /**
00172  * appends components from src to dst (both must be names)
00173  * @returns < 0 for an error
00174  * @returns the number of components copied otherwise
00175  */
00176 int
00177 SyncAppendAllComponents(struct ccn_charbuf *dst,
00178                         const struct ccn_charbuf *src);
00179 
00180 /**
00181  * Convenience routine to make a name from a ccn_indexbuf.
00182  * The storage for the returned charbuf is owned by the caller.
00183  * @returns a charbuf for the name (NULL if an error)
00184  */
00185 struct ccn_charbuf *
00186 SyncNameForIndexbuf(const unsigned char *buf, struct ccn_indexbuf *comps);
00187 
00188 /**
00189  * Convenience routine to make a uri for a name.
00190  * The storage for the returned charbuf is owned by the caller.
00191  * @returns the charbuf with the uri for the name (NULL if an error)
00192  */
00193 struct ccn_charbuf *
00194 SyncUriForName(struct ccn_charbuf *name);
00195 
00196 /////////////////////////////////////////////////////////////////
00197 // Routines for dealing with hashes.
00198 /////////////////////////////////////////////////////////////////
00199 
00200 /**
00201  * finds the hash code, storing the pointer to *xp and the length to *xs
00202  * if the hash is valid (test for *xs != 0 to be sure)
00203  * a hash code may be a ContentHash, or the last component of a Name
00204  * (for convenience, a Component may also be used)
00205  * non-destructive to the decoder
00206  * no error codes, but a pointer is set only for valid cases
00207  */
00208 void
00209 SyncGetHashPtr(const struct ccn_buf_decoder *hd,
00210                const unsigned char **xp, ssize_t *xs);
00211 
00212 ssize_t
00213 SyncCmpHashesRaw(const unsigned char *xp, ssize_t xs,
00214                  const unsigned char *yp, ssize_t ys);
00215 
00216 // accumulates a simple hash code into the hash accumulator
00217 // hash code is raw bytes
00218 void
00219 SyncAccumHashRaw(struct SyncLongHashStruct *hp,
00220                  const unsigned char *xp, size_t xs);
00221 
00222 // accumulates a simple hash code referenced by a decoder
00223 // into the hash accumulator for the composite node
00224 // non-destructive of decoder
00225 void
00226 SyncAccumHashInner(struct SyncLongHashStruct *hp,
00227                    const struct ccn_buf_decoder *d);
00228 
00229 // accumulates a simple hash code referenced by a decoder
00230 // into the hash accumulator for the composite node
00231 // non-destructive of decoder
00232 void
00233 SyncAccumHash(struct SyncLongHashStruct *hp, const struct ccn_charbuf *cb);
00234 
00235 // convert long hash to charbuf
00236 extern struct ccn_charbuf *
00237 SyncLongHashToBuf(const struct SyncLongHashStruct *hp);
00238 
00239 // makes a small, unsigned hash code from a full hash
00240 // useful to speed up hash table lookups
00241 uint32_t
00242 SyncSmallHash(const unsigned char * xp, ssize_t xs);
00243 
00244 
00245 /////////////////////////////////////////////////////////////////
00246 // Routines for appending numbers, hashes and names to a charbuf.
00247 /////////////////////////////////////////////////////////////////
00248 
00249 // appends a dtag and an unsigned number
00250 int
00251 SyncAppendTaggedNumber(struct ccn_charbuf *cb,
00252                        enum ccn_dtag dtag,
00253                        unsigned val);
00254 
00255 // appends a sequence of random bytes
00256 int
00257 SyncAppendRandomBytes(struct ccn_charbuf *cb, int n);
00258 
00259 // appends a random hash code as a ContentHash
00260 int
00261 SyncAppendRandomHash(struct ccn_charbuf *cb, int n);
00262 
00263 // appends a random name of nComp random-length components plus a random hash
00264 int
00265 SyncAppendRandomName(struct ccn_charbuf *cb, int nComp, int maxCompLen);
00266 
00267 // appendElementInner appends the ccnb encoding from the decoder to the cb output
00268 // types supported: CCN_DTAG_Name, CCN_DTAG_SyncContentHash, CCN_DTAG_BinaryValue
00269 // any error returns < 0
00270 // this routine advances the decoder!
00271 int
00272 SyncAppendElementInner(struct ccn_charbuf *cb, struct ccn_buf_decoder *d);
00273 
00274 // appendElement appends the ccnb encoding from the src to the dst
00275 // types supported: CCN_DTAG_Name, CCN_DTAG_SyncContentHash, CCN_DTAG_BinaryValue
00276 // any error returns < 0
00277 int
00278 SyncAppendElement(struct ccn_charbuf *dst, const struct ccn_charbuf *src);
00279 
00280 struct ccn_charbuf *
00281 SyncExtractName(struct ccn_buf_decoder *d);
00282 
00283 struct ccn_charbuf *
00284 SyncCopyName(const struct ccn_charbuf *name);
00285 
00286 ///////////////////////////////////////////////////////
00287 // Routines for simple parsing
00288 ///////////////////////////////////////////////////////
00289 
00290 unsigned
00291 SyncParseUnsigned(struct ccn_buf_decoder *d, enum ccn_dtag dtag);
00292 
00293 ssize_t
00294 SyncParseHash(struct ccn_buf_decoder *d);
00295 
00296 ssize_t
00297 SyncParseName(struct ccn_buf_decoder *d);
00298 
00299 ////////////////////////////////////////
00300 // Name and Node Accumulators
00301 ////////////////////////////////////////
00302 
00303 struct SyncNameAccumEntry {
00304     struct ccn_charbuf *name;
00305     intmax_t data;
00306 };
00307 
00308 struct SyncNameAccum {
00309     int len;
00310     int lim;
00311     struct SyncNameAccumEntry *ents;
00312 };
00313 
00314 /**
00315  * @returns a new name accum with at least lim space for names
00316  */
00317 struct SyncNameAccum *
00318 SyncAllocNameAccum(int lim);
00319 
00320 /**
00321  * frees the name accum, but not the names
00322  * @returns NULL
00323  */
00324 struct SyncNameAccum *
00325 SyncFreeNameAccum(struct SyncNameAccum *na);
00326 
00327 /**
00328  * frees the name accum and all of the names
00329  * @returns NULL
00330  */
00331 struct SyncNameAccum *
00332 SyncFreeNameAccumAndNames(struct SyncNameAccum *na);
00333 
00334 /**
00335  * default sorter callback for a name accum
00336  * uses CCN standard name order
00337  */
00338 int
00339 SyncNameAccumSorter(IndexSorter_Base base,
00340                     IndexSorter_Index x, IndexSorter_Index y);
00341 
00342 /**
00343  * appends a new name with associated data
00344  * important: the name is not copied!
00345  */
00346 int
00347 SyncNameAccumAppend(struct SyncNameAccum *na,
00348                     struct ccn_charbuf *name,
00349                     intmax_t data);
00350 
00351 /**
00352  * canonicalizes a name with respect to the given name accum
00353  * should be used for relatively small canon sets
00354  * @returns an equal name if it was in the accum
00355  * @returns a copy of the name (and enters it) if no equal name was in the accum
00356  */
00357 struct ccn_charbuf *
00358 SyncNameAccumCanon(struct SyncNameAccum *na,
00359                    const struct ccn_charbuf *name);
00360 
00361 struct SyncNodeAccum {
00362     int len;
00363     int lim;
00364     struct SyncNodeComposite **ents;
00365 };
00366 
00367 struct SyncNodeAccum *
00368 SyncAllocNodeAccum(int lim);
00369 
00370 struct SyncNodeAccum *
00371 SyncFreeNodeAccum(struct SyncNodeAccum *na);
00372 
00373 void
00374 SyncAccumNode(struct SyncNodeAccum *na, struct SyncNodeComposite *nc);
00375 
00376 ///////////////////////////////////////////////////////
00377 // Routines for simple interest creation
00378 ///////////////////////////////////////////////////////
00379 
00380 /**
00381  * given a spec for the desired fields
00382  * (scope, lifetime, maxSuffix, child are omitted if negative)
00383  * @returns the encoding for an interest
00384  */
00385 struct ccn_charbuf *
00386 SyncGenInterest(struct ccn_charbuf *name,
00387                 int scope,
00388                 int lifetime,
00389                 int maxSuffix,
00390                 int childPref,
00391                 struct SyncNameAccum *excl);
00392 
00393 ///////////////////////////////////////////////////////
00394 // Routines for local repo read/write
00395 ///////////////////////////////////////////////////////
00396 
00397 /**
00398  * given a sync node hash,
00399  * @returns the local repo name for the node
00400  */
00401 struct ccn_charbuf *
00402 SyncNameForLocalNode(struct SyncRootStruct *root, struct ccn_charbuf *hash);
00403 
00404 /**
00405  * given a charbuf cb for a content object, with optional parsing offsets in pco,
00406  * sets *xp and *xs with the pointer and length of the actual content bytes
00407  * @returns < 0 for failure
00408  */
00409 int
00410 SyncPointerToContent(struct ccn_charbuf *cb, struct ccn_parsed_ContentObject *pco,
00411                      const unsigned char **xp, size_t *xs);
00412 
00413 
00414 /**
00415  * given a charbuf cb and name for a content object, signs the bytes and
00416  * @returns the signed buffer (NULL for failure)
00417  */
00418 struct ccn_charbuf *
00419 SyncSignBuf(struct SyncBaseStruct *base,
00420             struct ccn_charbuf *cb,
00421             struct ccn_charbuf *name,
00422             long fresh, int flags);
00423 
00424 
00425 /**
00426  * given a local repo name and a buffer to fill,
00427  * fills cb with the content object (note: not the content itself)
00428  * pco is filled as a useful side effect, but may be NULL
00429  * @returns < 0 if the node fails
00430  */
00431 int
00432 SyncLocalRepoFetch(struct SyncBaseStruct *base,
00433                    struct ccn_charbuf *name,
00434                    struct ccn_charbuf *cb,
00435                    struct ccn_parsed_ContentObject *pco);
00436 
00437 
00438 /**
00439  * given a sync node hash,
00440  * @returns the local repo name for the node
00441  */
00442 int
00443 SyncLocalRepoStore(struct SyncBaseStruct *base,
00444                    struct ccn_charbuf *name,
00445                    struct ccn_charbuf *content,
00446                    int flags);
00447 
00448 #endif
00449 
Generated on Tue Aug 21 14:54:19 2012 for Content-Centric Networking in C by  doxygen 1.6.3