sync.h

Go to the documentation of this file.
00001 /**
00002  * @file ccn/sync.h
00003  * 
00004  * Sync library interface.
00005  * Defines a library interface to the Sync protocol facilities implemented
00006  * by the Repository
00007  *
00008  * Part of the CCNx C Library.
00009  *
00010  * Copyright (C) 2012 Palo Alto Research Center, Inc.
00011  *
00012  * This library is free software; you can redistribute it and/or modify it
00013  * under the terms of the GNU Lesser General Public License version 2.1
00014  * as published by the Free Software Foundation.
00015  * This library is distributed in the hope that it will be useful,
00016  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00017  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00018  * Lesser General Public License for more details. You should have received
00019  * a copy of the GNU Lesser General Public License along with this library;
00020  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00021  * Fifth Floor, Boston, MA 02110-1301 USA.
00022  */
00023 
00024 #ifndef CCNS_DEFINED
00025 #define CCNS_DEFINED
00026 
00027 #include <stddef.h>
00028 #include <ccn/charbuf.h>
00029 
00030 #define SLICE_VERSION 20110614
00031 
00032 struct ccns_slice;
00033 struct ccns_handle;
00034 
00035 typedef int (*ccns_callback)(struct ccns_handle *ccns,
00036                              struct ccn_charbuf *lhash,
00037                              struct ccn_charbuf *rhash,
00038                              struct ccn_charbuf *pname);
00039 
00040 /**
00041  * Allocate a ccns_slice structure
00042  * @returns a pointer to a new ccns_slice structure
00043  */
00044 struct ccns_slice *ccns_slice_create(void);
00045 
00046 /**
00047  * Deallocate a ccns_slice structure
00048  * @param a pointer to a pointer to a ccns_slice structure.  The pointer will
00049  *  be set to NULL on return.
00050  */
00051 void ccns_slice_destroy(struct ccns_slice **sp);
00052 
00053 /*
00054  * Set the topo and prefix fields of a slice
00055  * @param slice is the slice to be modified
00056  * @param t is a charbuf containing the topo prefix (used to route Sync commands)
00057  * @param p is a charbuf containing the prefix
00058  * @returns 0 on success, -1 otherwise.
00059  */
00060 int ccns_slice_set_topo_prefix(struct ccns_slice *slice, struct ccn_charbuf *t,
00061                                struct ccn_charbuf *p);
00062 
00063 /**
00064  * Add a (filter) clause to a ccns_slice structure
00065  * @param slice is the slice to be modified
00066  * @param f is a filter clause ccnb-encoded as a Name
00067  * @returns 0 on success, -1 otherwise.
00068  */
00069 int ccns_slice_add_clause(struct ccns_slice *s, struct ccn_charbuf *f);
00070 
00071 /**
00072  * Construct the name of a Sync configuration slice.
00073  * @param nm is a ccn_charbuf into which will be stored the slice name
00074  * @param s is the slice structure for which the name is required.
00075  * @returns 0 on success, -1 otherwise.
00076  */
00077 int ccns_slice_name(struct ccn_charbuf *nm, struct ccns_slice *s);
00078 
00079 /**
00080  * Read a slice given the name.
00081  * @param h is the ccn_handle on which to read.
00082  * @param name is the charbuf containing the name of the sync slice to be read.
00083  * @param slice is a pointer to a ccns_slice object which will be filled in
00084  *  on successful return.
00085  * @returns 0 on success, -1 otherwise.
00086  * XXX: should name be permitted to have trailing segment?
00087  */
00088 int ccns_read_slice(struct ccn *h, struct ccn_charbuf *name,
00089                         struct ccns_slice *slice);
00090 
00091 /**
00092  * Write a ccns_slice object to a repository.
00093  * @param h is the ccn_handle on which to write.
00094  * @param slice is a pointer to a ccns_slice object to be written.
00095  * @param name, if non-NULL, is a pointer to a charbuf which will be filled
00096  *  in with the name of the slice that was written.
00097  * @returns 0 on success, -1 otherwise.
00098  */
00099 int ccns_write_slice(struct ccn *h, struct ccns_slice *slice,
00100                          struct ccn_charbuf *name);
00101 
00102 /**
00103  * Delete a ccns_slice object from a repository.
00104  * @param h is the ccn_handle on which to write.
00105  * @param name is a pointer to a charbuf naming the slice to be deleted.
00106  * @returns 0 on success, -1 otherwise.
00107  */
00108 int ccns_delete_slice(struct ccn *h, struct ccn_charbuf *name);
00109 
00110 /**
00111  * Start notification of addition of names to a sync slice.
00112  * @param h is the ccn_handle on which to communicate.
00113  * @param slice is the slice to be opened.
00114  * @param callback is the procedure which will be called for each new name,
00115  *  and returns 0 to continue enumeration, -1 to stop further enumeration.
00116  *  NOTE: It is not safe to call ccns_close from within the callback.
00117  * @param rhash
00118  *      If NULL, indicates that the enumeration should start from the empty set.
00119  *      If non-NULL but empty, indicates that the enumeration should start from
00120  *      the current root.
00121  *      If non-NULL, and not empty, indicates that the enumeration should start
00122  *      from the specified root hash
00123  * @param pname if non-NULL represents the starting name for enumeration within
00124  *  the sync tree represented by the root hash rhash.
00125  * @returns a pointer to a new sync handle, which will be freed at close.
00126  */
00127 struct ccns_handle *ccns_open(struct ccn *h,
00128                                       struct ccns_slice *slice,
00129                                       ccns_callback callback,
00130                                       struct ccn_charbuf *rhash,
00131                                       struct ccn_charbuf *pname);
00132 
00133 /**
00134  * Stop notification of changes of names in a sync slice and free the handle.
00135  * @param sh is a pointer (to a pointer) to the sync handle returned
00136  *  by ccns_open, which will be freed and set to NULL.
00137  * @param rhash if non-NULL will be filled in with the current root hash.
00138  * @param pname if non-NULL will be filled in with the starting name
00139  *  for enumeration within the sync tree represented by the root hash rhash.
00140  */
00141 void ccns_close(struct ccns_handle **sh, struct ccn_charbuf *rhash, struct ccn_charbuf *pname);
00142 
00143 #endif
00144 
Generated on Tue Aug 21 14:54:17 2012 for Content-Centric Networking in C by  doxygen 1.6.3