aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2009-01-30 00:07:53 +0100
committerMax Kellermann <max@duempel.org>2009-01-30 00:07:53 +0100
commit297101c3f869abe02aeb642774f6c82b75fcfe81 (patch)
treea4617a562decdd14b19a392994abbc0bb1088cf6 /src
parent864dee823dada1774d3559d19ba96924bfaca06b (diff)
downloadmpd-297101c3f869abe02aeb642774f6c82b75fcfe81.tar.gz
mpd-297101c3f869abe02aeb642774f6c82b75fcfe81.tar.xz
mpd-297101c3f869abe02aeb642774f6c82b75fcfe81.zip
input_stream: documented the API
Diffstat (limited to 'src')
-rw-r--r--src/input_stream.h92
1 files changed, 83 insertions, 9 deletions
diff --git a/src/input_stream.h b/src/input_stream.h
index 5761adc12..f57ac3120 100644
--- a/src/input_stream.h
+++ b/src/input_stream.h
@@ -37,33 +37,92 @@ struct input_plugin {
};
struct input_stream {
+ /**
+ * the plugin which implements this input stream
+ */
const struct input_plugin *plugin;
- bool seekable;
+ /**
+ * an opaque pointer managed by the plugin
+ */
+ void *data;
+
+ /**
+ * indicates whether the stream is ready for reading and
+ * whether the other attributes in this struct are valid
+ */
bool ready;
+ /**
+ * if true, then the stream is fully seekable
+ */
+ bool seekable;
+
+ /**
+ * an optional errno error code, set to non-zero after an error occured
+ */
int error;
- off_t size, offset;
- char *mime;
- void *data;
+ /**
+ * the size of the resource, or -1 if unknown
+ */
+ off_t size;
+
+ /**
+ * the current offset within the stream
+ */
+ off_t offset;
+
+ /**
+ * the MIME content type of the resource, or NULL if unknown
+ */
+ char *mime;
void *archive;
};
+/**
+ * Initializes this library and all input_stream implementations.
+ */
void input_stream_global_init(void);
+/**
+ * Deinitializes this library and all input_stream implementations.
+ */
void input_stream_global_finish(void);
-/* if an error occurs for these 3 functions, then -1 is returned and errno
- for the input stream is set */
+/**
+ * Opens a new input stream. You may not access it until the "ready"
+ * flag is set.
+ *
+ * @param is the input_stream object allocated by the caller
+ * @return true on success
+ */
bool
input_stream_open(struct input_stream *is, const char *url);
+/**
+ * Closes the input stream and free resources. This does not free the
+ * input_stream pointer itself, because it is assumed to be allocated
+ * by the caller.
+ */
+void
+input_stream_close(struct input_stream *is);
+
+/**
+ * Seeks to the specified position in the stream. This will most
+ * likely fail if the "seekable" flag is false.
+ *
+ * @param is the input_stream object
+ * @param offset the relative offset
+ * @param whence the base of the seek, one of SEEK_SET, SEEK_CUR, SEEK_END
+ */
bool
input_stream_seek(struct input_stream *is, off_t offset, int whence);
-void input_stream_close(struct input_stream *is);
+/**
+ * Returns true if the stream has reached end-of-file.
+ */
bool input_stream_eof(struct input_stream *is);
/**
@@ -75,10 +134,25 @@ bool input_stream_eof(struct input_stream *is);
struct tag *
input_stream_tag(struct input_stream *is);
-/* return value: -1 is error, 1 inidicates stuff was buffered, 0 means nothing
- was buffered */
+/**
+ * Reads some of the stream into its buffer. The following return
+ * codes are defined: -1 = error, 1 = something was buffered, 0 =
+ * nothing was buffered.
+ *
+ * The semantics of this function are not well-defined, and it will
+ * eventually be removed.
+ */
int input_stream_buffer(struct input_stream *is);
+/**
+ * Reads data from the stream into the caller-supplied buffer.
+ * Returns 0 on error or eof (check with input_stream_eof()).
+ *
+ * @param is the input_stream object
+ * @param ptr the buffer to read into
+ * @param size the maximum number of bytes to read
+ * @return the number of bytes read
+ */
size_t
input_stream_read(struct input_stream *is, void *ptr, size_t size);