aboutsummaryrefslogtreecommitdiffstats
path: root/src/input_stream.h
blob: d8698c4cd247241b219a271cd8fd6ed368a97239 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
/* the Music Player Daemon (MPD)
 * Copyright (C) 2003-2007 by Warren Dukes (warren.dukes@gmail.com)
 * This project's homepage is: http://www.musicpd.org
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef MPD_INPUT_STREAM_H
#define MPD_INPUT_STREAM_H

#include <stddef.h>
#include <stdbool.h>
#include <sys/types.h>

struct input_stream;

struct input_plugin {
	bool (*open)(struct input_stream *is, const char *url);
	void (*close)(struct input_stream *is);

	struct tag *(*tag)(struct input_stream *is);
	int (*buffer)(struct input_stream *is);
	size_t (*read)(struct input_stream *is, void *ptr, size_t size);
	bool (*eof)(struct input_stream *is);
	bool (*seek)(struct input_stream *is, off_t offset, int whence);
};

struct input_stream {
	/**
	 * the plugin which implements this input stream
	 */
	const struct input_plugin *plugin;

	/**
	 * 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;

	/**
	 * 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;
};

/**
 * 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);

/**
 * 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);

/**
 * Returns true if the stream has reached end-of-file.
 */
bool input_stream_eof(struct input_stream *is);

/**
 * Reads the tag from the stream.
 *
 * @return a tag object which must be freed with tag_free(), or NULL
 * if the tag has not changed since the last call
 */
struct tag *
input_stream_tag(struct input_stream *is);

/**
 * 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);

#endif