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

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