]> code.delx.au - pulseaudio/blobdiff - polyp/polyplib-def.h
Make the whole stuff LGPL only
[pulseaudio] / polyp / polyplib-def.h
index 067ebf891b1dff74f4f957f551b873bf02d622f4..e2fbaea5d0cc8e34f2a56e3228790cdeff66309d 100644 (file)
@@ -7,22 +7,25 @@
   This file is part of polypaudio.
  
   polypaudio 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.
+  it under the terms of the GNU Lesser General Public License as
+  published by the Free Software Foundation; either version 2.1 of the
+  License, or (at your option) any later version.
  
   polypaudio 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.
+  Lesser General Public License for more details.
  
-  You should have received a copy of the GNU General Public License
-  along with polypaudio; if not, write to the Free Software
+  You should have received a copy of the GNU Lesser General Public
+  License along with polypaudio; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   USA.
 ***/
 
 #include <inttypes.h>
+#include <sys/time.h>
+#include <time.h>
+
 #include "cdecl.h"
 #include "sample.h"
 
@@ -69,6 +72,26 @@ enum pa_stream_direction {
     PA_STREAM_UPLOAD         /**< Sample upload stream */
 };
 
+/** Some special flags for stream connections. \since 0.6 */
+enum pa_stream_flags {
+    PA_STREAM_START_CORKED = 1,       /**< Create the stream corked, requiring an explicit pa_stream_cork() call to uncork it. */
+    PA_STREAM_INTERPOLATE_LATENCY = 2 /**< Interpolate the latency for
+                                       * this stream. When enabled,
+                                       * you can use
+                                       * pa_stream_interpolated_xxx()
+                                       * for synchronization. Using
+                                       * these functions instead of
+                                       * pa_stream_get_latency() has
+                                       * the advantage of not
+                                       * requiring a whole roundtrip
+                                       * for responses. Consider using
+                                       * this option when frequently
+                                       * requesting latency
+                                       * information. This is
+                                       * especially useful on long latency
+                                       * network connections. */
+};
+
 /** Playback and record buffer metrics */
 struct pa_buffer_attr{
     uint32_t maxlength;      /**< Maximum length of the buffer */
@@ -94,6 +117,7 @@ enum {
     PA_ERROR_CONNECTIONTERMINATED,   /**< Connection terminated */
     PA_ERROR_KILLED,                 /**< Entity killed */
     PA_ERROR_INVALIDSERVER,          /**< Invalid server */
+    PA_ERROR_INITFAILED,             /**< Module initialization failed */
     PA_ERROR_MAX                     /**< Not really an error but the first invalid error code */
 };
 
@@ -107,7 +131,8 @@ enum pa_subscription_mask {
     PA_SUBSCRIPTION_MASK_MODULE = 16,            /**< Module events */
     PA_SUBSCRIPTION_MASK_CLIENT = 32,            /**< Client events */
     PA_SUBSCRIPTION_MASK_SAMPLE_CACHE = 64,      /**< Sample cache events */
-    PA_SUBSCRIPTION_MASK_SERVER = 128            /**< Other global server changes. \since 0.4 */
+    PA_SUBSCRIPTION_MASK_SERVER = 128,           /**< Other global server changes. \since 0.4 */
+    PA_SUBSCRIPTION_MASK_AUTOLOAD = 256          /**< Autoload table events. \since 0.5 */
 };
 
 /** Subscription event types, as used by pa_context_subscribe() */
@@ -120,7 +145,8 @@ enum pa_subscription_event_type {
     PA_SUBSCRIPTION_EVENT_CLIENT = 5,         /**< Event type: Client */
     PA_SUBSCRIPTION_EVENT_SAMPLE_CACHE = 6,   /**< Event type: Sample cache item */
     PA_SUBSCRIPTION_EVENT_SERVER = 7,         /**< Event type: Global server change, only occuring with PA_SUBSCRIPTION_EVENT_CHANGE. \since 0.4  */
-    PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 7,  /**< A mask to extract the event type from an event value */
+    PA_SUBSCRIPTION_EVENT_AUTOLOAD = 8,       /**< Event type: Autoload table changes. \since 0.5 */
+    PA_SUBSCRIPTION_EVENT_FACILITY_MASK = 15, /**< A mask to extract the event type from an event value */
 
     PA_SUBSCRIPTION_EVENT_NEW = 0,            /**< A new object was created */
     PA_SUBSCRIPTION_EVENT_CHANGE = 16,        /**< A property of the object was modified */
@@ -131,18 +157,55 @@ enum pa_subscription_event_type {
 /** Return one if an event type t matches an event mask bitfield */
 #define pa_subscription_match_flags(m, t) (!!((m) & (1 << ((t) & PA_SUBSCRIPTION_EVENT_FACILITY_MASK))))
 
-/** A structure for latency info. See pa_stream_get_latency().  The
- * total latency a sample that is written with pa_stream_write() takes
- * to be played is buffer_usec+sink_usec. The buffer to which
+/** A structure for latency info. See pa_stream_get_latency(). The
+ * total output latency a sample that is written with
+ * pa_stream_write() takes to be played may be estimated by
+ * sink_usec+buffer_usec+transport_usec. The output buffer to which
  * buffer_usec relates may be manipulated freely (with
  * pa_stream_write()'s delta argument, pa_stream_flush() and friends),
- * the playback buffer sink_usec relates to is a FIFO which cannot be
- * flushed or manipulated in any way. */
+ * the buffers sink_usec/source_usec relates to is a first-in
+ * first-out buffer which cannot be flushed or manipulated in any
+ * way. The total input latency a sample that is recorded takes to be
+ * delivered to the application is:
+ * source_usec+buffer_usec+transport_usec-sink_usec. (Take care of
+ * sign issues!) When connected to a monitor source sink_usec contains
+ * the latency of the owning sink.*/
 struct pa_latency_info {
-    pa_usec_t buffer_usec;    /**< Time in usecs the current buffer takes to play */
-    pa_usec_t sink_usec;      /**< Time in usecs a sample takes to be played on the sink.  */
-    int playing;              /**< Non-zero when the stream is currently playing */
-    uint32_t queue_length;    /**< Queue size in bytes. */  
+    pa_usec_t buffer_usec;    /**< Time in usecs the current buffer takes to play. For both playback and record streams. */
+    pa_usec_t sink_usec;      /**< Time in usecs a sample takes to be played on the sink. For playback streams and record streams connected to a monitor source. */
+    pa_usec_t source_usec;    /**< Time in usecs a sample takes from being recorded to being delivered to the application. Only for record streams. \since 0.5*/
+    pa_usec_t transport_usec; /**< Estimated time in usecs a sample takes to be transferred to/from the daemon. For both playback and record streams. \since 0.5 */
+    int playing;              /**< Non-zero when the stream is currently playing. Only for playback streams. */
+    uint32_t queue_length;    /**< Queue size in bytes. For both playback and recrd streams. */
+    int synchronized_clocks;  /**< Non-zero if the local and the
+                               * remote machine have synchronized
+                               * clocks. If synchronized clocks are
+                               * detected transport_usec becomes much
+                               * more reliable. However, the code that
+                               * detects synchronized clocks is very
+                               * limited und unreliable itself. \since
+                               * 0.5 */
+    struct timeval timestamp; /**< The time when this latency info was current */
+    uint64_t counter;         /**< The byte counter current when the latency info was requested. \since 0.6 */
+};
+
+/** A structure for the spawn api. This may be used to integrate auto
+ * spawned daemons into your application. For more information see
+ * pa_context_connect(). When spawning a new child process the
+ * waitpid() is used on the child's PID. The spawn routine will not
+ * block or ignore SIGCHLD signals, since this cannot be done in a
+ * thread compatible way. You might have to do this in
+ * prefork/postfork. \since 0.4 */
+struct pa_spawn_api {
+    void (*prefork)(void);     /**< Is called just before the fork in the parent process. May be NULL. */
+    void (*postfork)(void);    /**< Is called immediately after the fork in the parent process. May be NULL.*/
+    void (*atfork)(void);      /**< Is called immediately after the
+                                * fork in the child process. May be
+                                * NULL. It is not safe to close all
+                                * file descriptors in this function
+                                * unconditionally, since a UNIX socket
+                                * (created using socketpair()) is
+                                * passed to the new process. */
 };
 
 PA_C_DECL_END