chiark / gitweb /
examples/disorder.init.in: Read settings from `/etc/default/disorder'.
[disorder] / lib / queue.h
1 /*
2  * This file is part of DisOrder.
3  * Copyright (C) 2004-2009 Richard Kettlewell
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation, either version 3 of the License, or
8  * (at your option) any later version.
9  * 
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  * 
15  * You should have received a copy of the GNU General Public License
16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
17  */
18 /** @file lib/queue.h
19  * @brief Track queues
20  *
21  * Used for the queue, the recently played list and the currently playing
22  * track, both in the server and in clients.
23  */
24 #ifndef QUEUE_H
25 #define QUEUE_H
26
27 #include <time.h>
28
29 /** @brief Possible track states */
30 enum playing_state {
31   /** @brief Track failed to play */
32   playing_failed,
33
34   /** @brief OBSOLETE
35    *
36    * Formerly denoted an unplayed scratch.  This is now indicated by @p
37    * playing_unplayed and @p origin_scratch.
38    */
39   playing_isscratch,
40
41   /** @brief OBSOLETE
42    *
43    * Formerly meant that no player could be found.  Nothing sets this any more.
44    */
45   playing_no_player,
46
47   /** @brief Play completed successfully
48    *
49    * Currently this actually means it finished decoding - it might still be
50    * buffered in the speaker, RTP player, sound card, etc.
51    *
52    * It might also mean that it's a (short!) track that hasn't been played at
53    * all yet but has been fully decoded ahead of time!  (This is very confusing
54    * so might change.)
55    */
56   playing_ok,
57
58   /** @brief Track is playing, but paused */
59   playing_paused,
60
61   /** @brief Track is playing but the server is quitting */
62   playing_quitting,
63
64   /** @brief OBSOLETE
65    *
66    * Formerly this meant a track that was picked at random and has not yet been
67    * played.  This situation is now indicated by @p playing_unplayed and @p
68    * origin_random (or @p origin_adopted).
69    */
70   playing_random,
71
72   /** @brief Track was scratched */
73   playing_scratched,
74
75   /** @brief Track is now playing
76    *
77    * This refers to the actual playing track, not something being decoded ahead
78    * of time.
79    */
80   playing_started,
81
82   /** @brief Track has not been played yet */
83   playing_unplayed
84 };
85
86 extern const char *const playing_states[];
87
88 /** @brief Possible track origins
89  *
90  * This is a newly introduced field.  The aim is ultimately to separate the
91  * concepts of the track origin and its current state.  NB that both are
92  * potentially mutable!
93  */
94 enum track_origin {
95   /** @brief Track was picked at random and then adopted by a user
96    *
97    * @c submitter identifies who adopted it.
98    */
99   origin_adopted,
100
101   /** @brief Track was picked by a user
102    *
103    * @c submitter identifies who picked it
104    */
105   origin_picked,
106
107   /** @brief Track was picked at random
108    *
109    * @c submitter will be NULL
110    */
111   origin_random,
112
113   /** @brief Track was scheduled by a user
114    *
115    * @c submitter identifies who picked it
116    */
117   origin_scheduled,
118
119   /** @brief Track is a scratch
120    *
121    * @c submitter identifies who did the scratching
122    */
123   origin_scratch
124 };
125
126 extern const char *const track_origins[];
127
128 /** @brief One queue/recently played entry
129  *
130  * The queue and recently played list form a doubly linked list with the head
131  * and tail referred to from @ref qhead and @ref phead.
132  */
133 struct queue_entry {
134   /** @brief Next entry */
135   struct queue_entry *next;
136
137   /** @brief Previous entry */
138   struct queue_entry *prev;
139
140   /** @brief Path to track (a database key) */
141   const char *track;
142
143   /** @brief Submitter or NULL
144    *
145    * Adopter, if @c origin is @ref origin_adopted.
146    */
147   const char *submitter;
148
149   /** @brief When submitted */
150   time_t when;
151
152   /** @brief When played */
153   time_t played;
154
155   /** @brief Current state
156    *
157    * Currently this includes some origin information but this is being phased
158    * out. */
159   enum playing_state state;
160
161   /** @brief Where track came from */
162   enum track_origin origin;
163
164   /** @brief Wait status from player
165    *
166    * Only valid in certain states (TODO).
167    */
168   long wstat;
169
170   /** @brief Who scratched this track or NULL */
171   const char *scratched;
172
173   /** @brief Unique ID string */
174   const char *id;
175
176   /** @brief Estimated starting time */
177   time_t expected;
178
179   /** @brief Type word from plugin (playing/buffered tracks only) */
180   unsigned long type;                   /* type word from plugin */
181
182   /** @brief Plugin for this track (playing/buffered tracks only) */
183   const struct plugin *pl;
184
185   /** @brief Player-specific data (playing/buffered tracks only) */
186   void *data;
187
188   /** @brief How much of track has been played so far (seconds) */
189   long sofar;
190
191   /** @brief True if track preparation is underway
192    *
193    * This is set when a decoder has been started and is expected to connect to
194    * the speaker, but the speaker has not sent as @ref SM_ARRIVED message back
195    * yet. */
196   int preparing;
197
198   /** @brief True if decoder is connected to speaker 
199    *
200    * This is not a @ref playing_state for a couple of reasons
201    * - it is orthogonal to @ref playing_started and @ref playing_unplayed
202    * - it would have to be hidden to other users of @c queue_entry
203    *
204    * For non-raw tracks this should always be zero.
205    */
206   int prepared;
207   /* For DISORDER_PLAYER_PAUSES only: */
208
209   /** @brief When last paused or 0 */
210   time_t lastpaused;
211
212   /** @brief When last resumed or 0 */
213   time_t lastresumed;
214
215   /** @brief How much of track was played up to last pause (seconds) */
216   long uptopause;
217
218   /** @brief Owning queue (for Disobedience only) */
219   struct queuelike *ql;
220   
221   /** @brief Decoder (or player) process ID */
222   pid_t pid;
223
224   /** @brief Termination signal sent to subprocess
225    *
226    * Used to supress 'terminated' messages.
227    */
228   int killed;
229 };
230
231 void queue_insert_entry(struct queue_entry *b, struct queue_entry *n);
232 void queue_delete_entry(struct queue_entry *node);
233
234 int queue_unmarshall(struct queue_entry *q, const char *s,
235                      void (*error_handler)(const char *, void *),
236                      void *u);
237 /* unmarshall UTF-8 string @s@ into @q@ */
238
239 int queue_unmarshall_vec(struct queue_entry *q, int nvec, char **vec,
240                      void (*error_handler)(const char *, void *),
241                      void *u);
242 /* unmarshall pre-split string @vec@ into @q@ */
243
244 char *queue_marshall(const struct queue_entry *q);
245 /* marshall @q@ into a UTF-8 string */
246
247 void queue_free(struct queue_entry *q, int rest);
248
249 #endif /* QUEUE_H */
250
251 /*
252 Local Variables:
253 c-basic-offset:2
254 comment-column:40
255 fill-column:79
256 End:
257 */