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, see <http://www.gnu.org/licenses/>. 22 ***/ 23 24 #include <sys/types.h> 25 26 #include <pulse/context.h> 27 #include <pulse/stream.h> 28 #include <pulse/cdecl.h> 29 #include <pulse/version.h> 30 31 /** \page scache Sample Cache 32 * 33 * \section overv_sec Overview 34 * 35 * The sample cache provides a simple way of overcoming high network latencies 36 * and reducing bandwidth. Instead of streaming a sound precisely when it 37 * should be played, it is stored on the server and only the command to start 38 * playing it needs to be sent. 39 * 40 * \section create_sec Creation 41 * 42 * To create a sample, the normal stream API is used (see \ref streams). The 43 * function pa_stream_connect_upload() will make sure the stream is stored as 44 * a sample on the server. 45 * 46 * To complete the upload, pa_stream_finish_upload() is called and the sample 47 * will receive the same name as the stream. If the upload should be aborted, 48 * simply call pa_stream_disconnect(). 49 * 50 * \section play_sec Playing samples 51 * 52 * To play back a sample, simply call pa_context_play_sample(): 53 * 54 * \code 55 * pa_operation *o; 56 * 57 * o = pa_context_play_sample(my_context, 58 * "sample2", // Name of my sample 59 * NULL, // Use default sink 60 * PA_VOLUME_NORM, // Full volume 61 * NULL, // Don't need a callback 62 * NULL 63 * ); 64 * if (o) 65 * pa_operation_unref(o); 66 * \endcode 67 * 68 * \section rem_sec Removing samples 69 * 70 * When a sample is no longer needed, it should be removed on the server to 71 * save resources. The sample is deleted using pa_context_remove_sample(). 72 */ 73 74 /** \file 75 * All sample cache related routines 76 * 77 * See also \subpage scache 78 */ 79 80 PA_C_DECL_BEGIN 81 82 /** Callback prototype for pa_context_play_sample_with_proplist(). The 83 * idx value is the index of the sink input object, or 84 * PA_INVALID_INDEX on failure. \since 0.9.11 */ 85 typedef void (*pa_context_play_sample_cb_t)(pa_context *c, uint32_t idx, void *userdata); 86 87 /** Make this stream a sample upload stream. Returns zero on success. */ 88 int pa_stream_connect_upload(pa_stream *s, size_t length); 89 90 /** Finish the sample upload, the stream name will become the sample 91 * name. You cancel a sample upload by issuing 92 * pa_stream_disconnect(). Returns zero on success. */ 93 int pa_stream_finish_upload(pa_stream *s); 94 95 /** Remove a sample from the sample cache. Returns an operation object which 96 * may be used to cancel the operation while it is running. */ 97 pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata); 98 99 /** Play a sample from the sample cache to the specified device. If 100 * the latter is NULL use the default sink. Returns an operation 101 * object */ 102 pa_operation* pa_context_play_sample( 103 pa_context *c /**< Context */, 104 const char *name /**< Name of the sample to play */, 105 const char *dev /**< Sink to play this sample on */, 106 pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ , 107 pa_context_success_cb_t cb /**< Call this function after successfully starting playback, or NULL */, 108 void *userdata /**< Userdata to pass to the callback */); 109 110 /** Play a sample from the sample cache to the specified device, 111 * allowing specification of a property list for the playback 112 * stream. If the latter is NULL use the default sink. Returns an 113 * operation object. \since 0.9.11 */ 114 pa_operation* pa_context_play_sample_with_proplist( 115 pa_context *c /**< Context */, 116 const char *name /**< Name of the sample to play */, 117 const char *dev /**< Sink to play this sample on */, 118 pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ , 119 const pa_proplist *proplist /**< Property list for this sound. The property list of the cached entry will have this merged into it. */, 120 pa_context_play_sample_cb_t cb /**< Call this function after successfully starting playback, or NULL */, 121 void *userdata /**< Userdata to pass to the callback */); 122 123 PA_C_DECL_END 124 125 #endif 126