disorder.h: more consistent approach to function attributes

[disorder] / lib / uaudio.h

diff --git a/lib/uaudio.h b/lib/uaudio.h
index d6376c895f399c522b65f4c490d857a458f3b55f..bcb4e949d95a5c7f94f058f7de12648401e82842 100644 (file)
--- a/lib/uaudio.h
+++ b/lib/uaudio.h
@@ -1,6 +1,6 @@
 /*
  * This file is part of DisOrder.
- * Copyright (C) 2009 Richard Kettlewell
+ * Copyright (C) 2009, 2013 Richard Kettlewell
  *
  * 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
@@ -23,11 +23,14 @@
 #ifndef UAUDIO_H
 #define UAUDIO_H
 
+struct sockaddr_storage;
+
 extern int uaudio_rate;
 extern int uaudio_bits;
 extern int uaudio_channels;
 extern int uaudio_signed;
 extern size_t uaudio_sample_size;
+extern int uaudio_buffer;
 
 /** @brief Callback to get audio data
  * @param buffer Where to put audio data
@@ -51,11 +54,33 @@ typedef size_t uaudio_callback(void *buffer,
 /** @brief Callback to play audio data
  * @param buffer Pointer to audio buffer
  * @param samples Number of samples to play
+ * @param flags Flags word
  * @return Number of samples played
  *
  * Used with uaudio_thread_start() etc.
+ *
+ * @p flags is a bitmap giving the current pause state and transitions:
+ * - @ref UAUDIO_PAUSE if this is the first call of a pause
+ * - @ref UAUDIO_RESUME if this is the first call of a resumse
+ * - @ref UAUDIO_PLAYING if this is outside a pause
+ * - @ref UAUDIO_PAUSED if this is in a pause
+ *
+ * During a pause, the sample data is guaranteed to be 0.
  */
-typedef size_t uaudio_playcallback(void *buffer, size_t samples);
+typedef size_t uaudio_playcallback(void *buffer, size_t samples,
+                                   unsigned flags);
+
+/** @brief Start of a pause */
+#define UAUDIO_PAUSE 0x0001
+
+/** @brief End of a pause */
+#define UAUDIO_RESUME 0x0002
+
+/** @brief Currently playing */
+#define UAUDIO_PLAYING 0x0004
+
+/** @brief Currently paused */
+#define UAUDIO_PAUSED 0x0008
 
 /** @brief Audio API definition */
 struct uaudio {
@@ -126,9 +151,17 @@ struct uaudio {
 
   /** @brief Set configuration */
   void (*configure)(void);
-  
+
+  /** @brief Descriptive flags */
+  unsigned flags;
 };
 
+/** @brief API is suitable for clients */
+#define UAUDIO_API_CLIENT 0x0001
+
+/** @brief API is suitable for servers */
+#define UAUDIO_API_SERVER 0x0002
+
 void uaudio_set_format(int rate, int channels, int samplesize, int signed_);
 void uaudio_set(const char *name, const char *value);
 char *uaudio_get(const char *name, const char *default_value);
@@ -139,21 +172,18 @@ void uaudio_thread_start(uaudio_callback *callback,
                          size_t max,
                          unsigned flags);
 
-/** @brief Fake pauses
- *
- * This flag is used for audio backends that cannot sensibly be paused.
- * The thread support code will supply silence while deactivated in this
- * case.
- */
-#define UAUDIO_THREAD_FAKE_PAUSE 0x00000001
-
 void uaudio_thread_stop(void);
 void uaudio_thread_activate(void);
 void uaudio_thread_deactivate(void);
-void uaudio_schedule_synchronize(void);
-void uaudio_schedule_update(size_t written_samples);
+uint32_t uaudio_schedule_sync(void);
+void uaudio_schedule_sent(size_t nsamples_sent);
 void uaudio_schedule_init(void);
 const struct uaudio *uaudio_find(const char *name);
+const struct uaudio *uaudio_default(const struct uaudio *const *apis,
+                                    unsigned context);
+
+int rtp_add_recipient(const struct sockaddr_storage *sa);
+int rtp_remove_recipient(const struct sockaddr_storage *sa);
 
 extern uint64_t uaudio_schedule_timestamp;
 extern int uaudio_schedule_reactivated;
@@ -170,6 +200,10 @@ extern const struct uaudio uaudio_alsa;
 extern const struct uaudio uaudio_oss;
 #endif
 
+#if HAVE_PULSEAUDIO
+extern const struct uaudio uaudio_pulseaudio;
+#endif
+
 extern const struct uaudio uaudio_rtp;
 
 extern const struct uaudio uaudio_command;