00001 /* 00002 * ccn/fetch.h 00003 * 00004 * Part of the CCNx C Library. 00005 * 00006 * Copyright (C) 2010-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 * @file ccn/fetch.h 00022 * Streaming access for fetching segmented CCNx data. 00023 * 00024 * Supports multiple streams from a single connection and 00025 * seeking to an arbitrary position within the associated file. 00026 */ 00027 00028 #ifndef CCN_FETCH_DEFINED 00029 #define CCN_FETCH_DEFINED 00030 00031 #include <stdio.h> 00032 #include <ccn/ccn.h> 00033 #include <ccn/uri.h> 00034 00035 /** 00036 * Creates a new ccn_fetch object using the given ccn connection. 00037 * If h == NULL, attempts to create a new connection automatically. 00038 * @returns NULL if the creation was not successful 00039 * (only can happen for the h == NULL case). 00040 */ 00041 struct ccn_fetch * 00042 ccn_fetch_new(struct ccn *h); 00043 00044 typedef enum { 00045 ccn_fetch_flags_None = 0, 00046 ccn_fetch_flags_NoteGlitch = 1, 00047 ccn_fetch_flags_NoteAddRem = 2, 00048 ccn_fetch_flags_NoteNeed = 4, 00049 ccn_fetch_flags_NoteFill = 8, 00050 ccn_fetch_flags_NoteFinal = 16, 00051 ccn_fetch_flags_NoteTimeout = 32, 00052 ccn_fetch_flags_NoteOpenClose = 64, 00053 ccn_fetch_flags_NoteAll = 0xffff 00054 } ccn_fetch_flags; 00055 00056 #define CCN_FETCH_READ_ZERO (-3) 00057 #define CCN_FETCH_READ_TIMEOUT (-2) 00058 #define CCN_FETCH_READ_NONE (-1) 00059 #define CCN_FETCH_READ_END (0) 00060 00061 /** 00062 * Sets the destination for debug output. NULL disables debug output. 00063 */ 00064 void 00065 ccn_fetch_set_debug(struct ccn_fetch *f, FILE *debug, ccn_fetch_flags flags); 00066 00067 /** 00068 * Destroys a ccn_fetch object. 00069 * Only destroys the underlying ccn connection if it was automatically created. 00070 * Forces all underlying streams to close immediately. 00071 * @returns NULL in all cases. 00072 */ 00073 struct ccn_fetch * 00074 ccn_fetch_destroy(struct ccn_fetch *f); 00075 00076 /** 00077 * Polls the underlying streams and attempts to make progress. 00078 * Scans the streams for those that have data already present, or are at the end 00079 * of the stream. If the count is 0, perfoms a ccn_poll on the underlying 00080 * ccn connection with a 0 timeout. 00081 * 00082 * NOTE: periodic calls to ccn_fetch_poll should be performed to update 00083 * the contents of the streams UNLESS the client is calling ccn_run for 00084 * the underlying ccn connection. 00085 * @returns the count of streams that have pending data or have ended. 00086 */ 00087 int 00088 ccn_fetch_poll(struct ccn_fetch *f); 00089 00090 /** 00091 * Provides an iterator through the underlying streams. 00092 * Use fs == NULL to start the iteration, and an existing stream to continue 00093 * the iteration. 00094 * @returns the next stream in the iteration, or NULL at the end. 00095 * Note that providing a stale (closed) stream handle will return NULL. 00096 */ 00097 struct ccn_fetch_stream * 00098 ccn_fetch_next(struct ccn_fetch *f, struct ccn_fetch_stream *fs); 00099 00100 /** 00101 * @returns the underlying ccn connection. 00102 */ 00103 struct ccn * 00104 ccn_fetch_get_ccn(struct ccn_fetch *f); 00105 00106 /** 00107 * Creates a stream for a named interest. 00108 * The name should be a ccnb encoded interest. 00109 * If resolveVersion, then we assume that the version is unresolved, 00110 * and an attempt is made to determine the version number using the highest 00111 * version. If interestTemplate == NULL then a suitable default is used. 00112 * The max number of buffers (maxBufs) is a hint, and may be clamped to an 00113 * implementation minimum or maximum. 00114 * If assumeFixed, then assume that the segment size is given by the first 00115 * segment fetched, otherwise segments may be of variable size. 00116 * @returns NULL if the stream creation failed, 00117 * otherwise returns the new stream. 00118 */ 00119 struct ccn_fetch_stream * 00120 ccn_fetch_open(struct ccn_fetch *f, struct ccn_charbuf *name, 00121 const char *id, 00122 struct ccn_charbuf *interestTemplate, 00123 int maxBufs, 00124 int resolveVersion, 00125 int assumeFixed); 00126 00127 /** 00128 * Closes the stream and reclaims any resources used by the stream. 00129 * The stream object will be freed, so the client must not access it again. 00130 * @returns NULL in all cases. 00131 */ 00132 struct ccn_fetch_stream * 00133 ccn_fetch_close(struct ccn_fetch_stream *fs); 00134 00135 /** 00136 * Tests for available bytes in the stream. 00137 * Determines how many bytes can be read on the given stream 00138 * without waiting (via ccn_fetch_poll). 00139 * @returns 00140 * CCN_FETCH_READ_TIMEOUT if a timeout occured, 00141 * CCN_FETCH_READ_ZERO if a zero-length segment was found 00142 * CCN_FETCH_READ_NONE if no bytes are immediately available 00143 * CCN_FETCH_READ_END if the stream is at the end, 00144 * and N > 0 if N bytes can be read without performing a poll. 00145 */ 00146 intmax_t 00147 ccn_fetch_avail(struct ccn_fetch_stream *fs); 00148 00149 /** 00150 * Reads bytes from a stream. 00151 * Reads at most len bytes into buf from the given stream. 00152 * Will not wait for bytes to arrive. 00153 * Advances the read position on a successful read. 00154 * @returns 00155 * CCN_FETCH_READ_TIMEOUT if a timeout occured, 00156 * CCN_FETCH_READ_ZERO if a zero-length segment was found 00157 * CCN_FETCH_READ_NONE if no bytes are immediately available 00158 * CCN_FETCH_READ_END if the stream is at the end, 00159 * and N > 0 if N bytes were read. 00160 */ 00161 intmax_t 00162 ccn_fetch_read(struct ccn_fetch_stream *fs, 00163 void *buf, 00164 intmax_t len); 00165 00166 /** 00167 * Resets the timeout indicator, which will cause pending interests to be 00168 * retried. The client determines conditions for a timeout to be considered 00169 * an unrecoverable error. 00170 */ 00171 void 00172 ccn_reset_timeout(struct ccn_fetch_stream *fs); 00173 00174 /** 00175 * Seeks to a position in a stream. 00176 * Sets the read position. 00177 * It is strongly recommended that the seek is only done to a position that 00178 * is either 0 or has resulted from a successful read. Otherwise 00179 * end of stream indicators may be returned for a seek beyond the end. 00180 * @returns -1 if the seek is to a bad position 00181 * or if the segment size is variable, otherwise returns 0. 00182 */ 00183 int 00184 ccn_fetch_seek(struct ccn_fetch_stream *fs, 00185 intmax_t pos); 00186 00187 /** 00188 * @returns the current read position (initially 0) 00189 */ 00190 intmax_t 00191 ccn_fetch_position(struct ccn_fetch_stream *fs); 00192 00193 #endif