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