src/pulse/scache.h

   1 #ifndef fooscachehfoo
   2 #define fooscachehfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as published
  12   by the Free Software Foundation; either version 2.1 of the License,
  13   or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <sys/types.h>
  27
  28 #include <pulse/context.h>
  29 #include <pulse/stream.h>
  30 #include <pulse/cdecl.h>
  31 #include <pulse/version.h>
  32
  33 /** \page scache Sample Cache
  34  *
  35  * \section overv_sec Overview
  36  *
  37  * The sample cache provides a simple way of overcoming high network latencies
  38  * and reducing bandwidth. Instead of streaming a sound precisely when it
  39  * should be played, it is stored on the server and only the command to start
  40  * playing it needs to be sent.
  41  *
  42  * \section create_sec Creation
  43  *
  44  * To create a sample, the normal stream API is used (see \ref streams). The
  45  * function pa_stream_connect_upload() will make sure the stream is stored as
  46  * a sample on the server.
  47  *
  48  * To complete the upload, pa_stream_finish_upload() is called and the sample
  49  * will receive the same name as the stream. If the upload should be aborted,
  50  * simply call pa_stream_disconnect().
  51  *
  52  * \section play_sec Playing samples
  53  *
  54  * To play back a sample, simply call pa_context_play_sample():
  55  *
  56  * \code
  57  * pa_operation *o;
  58  *
  59  * o = pa_context_play_sample(my_context,
  60  *                            "sample2",       // Name of my sample
  61  *                            NULL,            // Use default sink
  62  *                            PA_VOLUME_NORM,  // Full volume
  63  *                            NULL,            // Don't need a callback
  64  *                            NULL
  65  *                            );
  66  * if (o)
  67  *     pa_operation_unref(o);
  68  * \endcode
  69  *
  70  * \section rem_sec Removing samples
  71  *
  72  * When a sample is no longer needed, it should be removed on the server to
  73  * save resources. The sample is deleted using pa_context_remove_sample().
  74  */
  75
  76 /** \file
  77  * All sample cache related routines */
  78
  79 PA_C_DECL_BEGIN
  80
  81 /** Callback prototype for pa_context_play_sample_with_proplist(). The
  82  * idx value is the index of the sink input object, or
  83  * PA_INVALID_INDEX on failure. \since 0.9.11 */
  84 typedef void (*pa_context_play_sample_cb_t)(pa_context *c, uint32_t idx, void *userdata);
  85
  86 /** Make this stream a sample upload stream */
  87 int pa_stream_connect_upload(pa_stream *s, size_t length);
  88
  89 /** Finish the sample upload, the stream name will become the sample
  90  * name. You cancel a sample upload by issuing
  91  * pa_stream_disconnect() */
  92 int pa_stream_finish_upload(pa_stream *s);
  93
  94 /** Remove a sample from the sample cache. Returns an operation object which may be used to cancel the operation while it is running */
  95 pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
  96
  97 /** Play a sample from the sample cache to the specified device. If
  98  * the latter is NULL use the default sink. Returns an operation
  99  * object */
 100 pa_operation* pa_context_play_sample(
 101         pa_context *c               /**< Context */,
 102         const char *name            /**< Name of the sample to play */,
 103         const char *dev             /**< Sink to play this sample on */,
 104         pa_volume_t volume          /**< Volume to play this sample with. Starting with 0.9.15 you may pass here (pa_volume_t) -1 which will leave the decision about the volume to the server side which is a good idea. */ ,
 105         pa_context_success_cb_t cb  /**< Call this function after successfully starting playback, or NULL */,
 106         void *userdata              /**< Userdata to pass to the callback */);
 107
 108 /** Play a sample from the sample cache to the specified device,
 109  * allowing specification of a property list for the playback
 110  * stream. If the latter is NULL use the default sink. Returns an
 111  * operation object. \since 0.9.11 */
 112 pa_operation* pa_context_play_sample_with_proplist(
 113         pa_context *c                   /**< Context */,
 114         const char *name                /**< Name of the sample to play */,
 115         const char *dev                 /**< Sink to play this sample on */,
 116         pa_volume_t volume              /**< Volume to play this sample with. Starting with 0.9.15 you may pass here (pa_volume_t) -1 which will leave the decision about the volume to the server side which is a good idea.  */ ,
 117         pa_proplist *proplist           /**< Property list for this sound. The property list of the cached entry will be merged into this property list */,
 118         pa_context_play_sample_cb_t cb  /**< Call this function after successfully starting playback, or NULL */,
 119         void *userdata                  /**< Userdata to pass to the callback */);
 120
 121 PA_C_DECL_END
 122
 123 #endif