fetch.h

Go to the documentation of this file.
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 occurred,
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 occurred,
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

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