From 4695c1136d2663a67aa5ea564fd308489ce8ee9d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 26 May 2009 20:41:58 +0200 Subject: build-system: properly rename canberra.h to canberra.h.in --- src/canberra.h | 478 ------------------------------------------------------ src/canberra.h.in | 478 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 478 insertions(+), 478 deletions(-) delete mode 100644 src/canberra.h create mode 100644 src/canberra.h.in diff --git a/src/canberra.h b/src/canberra.h deleted file mode 100644 index c3e55c2..0000000 --- a/src/canberra.h +++ /dev/null @@ -1,478 +0,0 @@ -#ifndef foocanberrahfoo -#define foocanberrahfoo - -/*** - This file is part of libcanberra. - - Copyright 2008 Lennart Poettering - - libcanberra is free software; you can redistribute it and/or modify - 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. - - libcanberra 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 - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with libcanberra. If not, see - . -***/ - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -#ifndef __GNUC__ -/* Make sure __attribute__ works on non-gcc systems. Yes, might be a bit ugly */ -#define __attribute__(x) -#endif - -/** - * CA_MAJOR: - * - * Evaluates to the major version number of libcanberra. - */ -#define CA_MAJOR (@CA_MAJOR@) - -/** - * CA_MINOR: - * - * Evaluates to the minor version number of libcanberra. - */ -#define CA_MINOR (@CA_MINOR@) - -/** - * CA_CHECK_VERSION: - * - * Evaluates to TRUE when the library version is newer than the - * specified parameters. - */ -#define CA_CHECK_VERSION(major,minor) \ - (CA_MAJOR > (major) || \ - (CA_MAJOR == (major) && CA_MINOR >= (minor))) - -/** - * CA_PROP_MEDIA_NAME: - * - * A name describing the media being played. Localized if possible and applicable. - */ -#define CA_PROP_MEDIA_NAME "media.name" - -/** - * CA_PROP_MEDIA_TITLE: - * - * A (song) title describing the media being played. Localized if possible and applicable. - */ -#define CA_PROP_MEDIA_TITLE "media.title" - -/** - * CA_PROP_MEDIA_ARTIST: - * - * The artist of this media. Localized if possible and applicable. - */ -#define CA_PROP_MEDIA_ARTIST "media.artist" - -/** - * CA_PROP_MEDIA_LANGUAGE: - * - * The language this media is in, in some standard POSIX locale string, such as "de_DE". - */ -#define CA_PROP_MEDIA_LANGUAGE "media.language" - -/** - * CA_PROP_MEDIA_FILENAME: - * - * The file name this media was or can be loaded from. - */ -#define CA_PROP_MEDIA_FILENAME "media.filename" - -/** - * CA_PROP_MEDIA_ICON: - * - * An icon for this media in binary PNG format. - */ -#define CA_PROP_MEDIA_ICON "media.icon" - -/** - * CA_PROP_MEDIA_ICON_NAME: - * - * An icon name as defined in the XDG icon naming specifcation. - */ -#define CA_PROP_MEDIA_ICON_NAME "media.icon_name" - -/** - * CA_PROP_MEDIA_ROLE: - * - * The "role" this media is played in. For event sounds the string - * "event". For other cases strings like "music", "video", "game", ... - */ -#define CA_PROP_MEDIA_ROLE "media.role" - -/** - * CA_PROP_EVENT_ID: - * - * A textual id for an event sound, as mandated by the XDG sound naming specification. - */ -#define CA_PROP_EVENT_ID "event.id" - -/** - * CA_PROP_EVENT_DESCRIPTION: - * - * A descriptive string for the sound event. Localized if possible and applicable. - */ -#define CA_PROP_EVENT_DESCRIPTION "event.description" - -/** - * CA_PROP_EVENT_MOUSE_X: - * - * If this sound event was triggered by a mouse input event, the X - * position of the mouse cursor on the screen, formatted as string. - */ -#define CA_PROP_EVENT_MOUSE_X "event.mouse.x" - -/** - * CA_PROP_EVENT_MOUSE_Y: - * - * If this sound event was triggered by a mouse input event, the Y - * position of the mouse cursor on the screen, formatted as string. - */ -#define CA_PROP_EVENT_MOUSE_Y "event.mouse.y" - -/** - * CA_PROP_EVENT_MOUSE_HPOS: - * - * If this sound event was triggered by a mouse input event, the X - * position of the mouse cursor as fractional value between 0 and 1, - * formatted as string, 0 reflecting the left side of the screen, 1 - * the right side. - */ -#define CA_PROP_EVENT_MOUSE_HPOS "event.mouse.hpos" - -/** - * CA_PROP_EVENT_MOUSE_VPOS: - * - * If this sound event was triggered by a mouse input event, the Y - * position of the mouse cursor as fractional value between 0 and 1, - * formatted as string, 0 reflecting the top end of the screen, 1 - * the bottom end. - */ -#define CA_PROP_EVENT_MOUSE_VPOS "event.mouse.vpos" - -/** - * CA_PROP_EVENT_MOUSE_BUTTON: - * - * If this sound event was triggered by a mouse input event, the - * number of the mouse button that triggered it, formatted as string. 1 - * for left mouse button, 3 for right, 2 for middle. - */ -#define CA_PROP_EVENT_MOUSE_BUTTON "event.mouse.button" - -/** - * CA_PROP_WINDOW_NAME: - * - * If this sound event was triggered by a window on the screen, the - * name of this window as human readable string. - */ -#define CA_PROP_WINDOW_NAME "window.name" - -/** - * CA_PROP_WINDOW_ID: - * - * If this sound event was triggered by a window on the screen, some - * identification string for this window, so that the sound system can - * recognize specific windows. - */ -#define CA_PROP_WINDOW_ID "window.id" - -/** - * CA_PROP_WINDOW_ICON: - * - * If this sound event was triggered by a window on the screen, binary - * icon data in PNG format for this window. - */ -#define CA_PROP_WINDOW_ICON "window.icon" - -/** - * CA_PROP_WINDOW_ICON_NAME: - * - * If this sound event was triggered by a window on the screen, an - * icon name for this window, as defined in the XDG icon naming - * specification. - */ -#define CA_PROP_WINDOW_ICON_NAME "window.icon_name" - -/** - * CA_PROP_WINDOW_X11_DISPLAY: - * - * If this sound event was triggered by a window on the screen and the - * windowing system is X11, the X display name of the window (e.g. ":0"). - */ -#define CA_PROP_WINDOW_X11_DISPLAY "window.x11.display" - -/** - * CA_PROP_WINDOW_X11_SCREEN: - * - * If this sound event was triggered by a window on the screen and the - * windowing system is X11, the X screen id of the window formatted as - * string (e.g. "0"). - */ -#define CA_PROP_WINDOW_X11_SCREEN "window.x11.screen" - -/** - * CA_PROP_WINDOW_X11_MONITOR: - * - * If this sound event was triggered by a window on the screen and the - * windowing system is X11, the X monitor id of the window formatted as - * string (e.g. "0"). - */ -#define CA_PROP_WINDOW_X11_MONITOR "window.x11.monitor" - -/** - * CA_PROP_WINDOW_X11_XID: - * - * If this sound event was triggered by a window on the screen and the - * windowing system is X11, the XID of the window formatted as string. - */ -#define CA_PROP_WINDOW_X11_XID "window.x11.xid" - -/** - * CA_PROP_APPLICATION_NAME: - * - * The name of the application this sound event was triggered by as - * human readable string. (e.g. "GNU Emacs") Localized if possible and - * applicable. - */ -#define CA_PROP_APPLICATION_NAME "application.name" - -/** - * CA_PROP_APPLICATION_ID: - * - * An identifier for the program this sound event was triggered - * by. (e.g. "org.gnu.emacs"). - */ -#define CA_PROP_APPLICATION_ID "application.id" - -/** - * CA_PROP_APPLICATION_VERSION: - * - * A version number for the program this sound event was triggered - * by. (e.g. "22.2") - */ -#define CA_PROP_APPLICATION_VERSION "application.version" - -/** - * CA_PROP_APPLICATION_ICON: - * - * Binary icon data in PNG format for the application this sound event - * is triggered by. - */ -#define CA_PROP_APPLICATION_ICON "application.icon" - -/** - * CA_PROP_APPLICATION_ICON_NAME: - * - * An icon name for the application this sound event is triggered by, - * as defined in the XDG icon naming specification. - */ -#define CA_PROP_APPLICATION_ICON_NAME "application.icon_name" - -/** - * CA_PROP_APPLICATION_LANGUAGE: - * - * The locale string the application that is triggering this sound - * event is running in. A POSIX locale string such as de_DE@euro. - */ -#define CA_PROP_APPLICATION_LANGUAGE "application.language" - -/** - * CA_PROP_APPLICATION_PROCESS_ID: - * - * The unix PID of the process that is triggering this sound event, formatted as string. - */ -#define CA_PROP_APPLICATION_PROCESS_ID "application.process.id" - -/** - * CA_PROP_APPLICATION_PROCESS_BINARY: - * - * The path to the process binary of the process that is triggering this sound event. - */ -#define CA_PROP_APPLICATION_PROCESS_BINARY "application.process.binary" - -/** - * CA_PROP_APPLICATION_PROCESS_USER: - * - * The user that owns the process that is triggering this sound event. - */ -#define CA_PROP_APPLICATION_PROCESS_USER "application.process.user" - -/** - * CA_PROP_APPLICATION_PROCESS_HOST: - * - * The host name of the host the process that is triggering this sound event runs on. - */ -#define CA_PROP_APPLICATION_PROCESS_HOST "application.process.host" - -/** - * CA_PROP_CANBERRA_CACHE_CONTROL: - * - * A special property that can be used to control the automatic sound - * caching of sounds in the sound server. One of "permanent", - * "volatile", "never". "permanent" will cause this sample to be - * cached in the server permanently. This is useful for very - * frequently used sound events such as those used for input - * feedback. "volatile" may be used for cacheing sounds in the sound - * server temporarily. They will expire after some time or on cache - * pressure. Finally, "never" may be used for sounds that should never - * be cached, because they are only generated very seldomly or even - * only once at most (such as desktop login sounds). - * - * If this property is not explicitly passed to ca_context_play() it - * will default to "never". If it is not explicitly passed to - * ca_context_cache() it will default to "permanent". - * - * If the list of properties is handed on to the sound server this - * property is stripped from it. - */ -#define CA_PROP_CANBERRA_CACHE_CONTROL "canberra.cache-control" - -/** - * CA_PROP_CANBERRA_VOLUME: - * - * A special property that can be used to control the volume this - * sound event is played in if the backend supports it. A floating - * point value for the decibel multiplier for the sound. 0 dB relates - * to zero gain, and is the default volume these sounds are played in. - * - * If the list of properties is handed on to the sound server this - * property is stripped from it. - */ -#define CA_PROP_CANBERRA_VOLUME "canberra.volume" - -/** - * CA_PROP_CANBERRA_XDG_THEME_NAME: - * - * A special property that can be used to control the XDG sound theme that - * is used for this sample. - * - * If the list of properties is handed on to the sound server this - * property is stripped from it. - */ -#define CA_PROP_CANBERRA_XDG_THEME_NAME "canberra.xdg-theme.name" - -/** - * CA_PROP_CANBERRA_XDG_THEME_OUTPUT_PROFILE: - * - * A special property that can be used to control the XDG sound theme - * output profile that is used for this sample. - * - * If the list of properties is handed on to the sound server this - * property is stripped from it. - */ -#define CA_PROP_CANBERRA_XDG_THEME_OUTPUT_PROFILE "canberra.xdg-theme.output-profile" - -/** - * CA_PROP_CANBERRA_ENABLE: - * - * A special property that can be used to control whether any sounds - * are played at all. If this property is "1" or unset sounds are - * played as normal. However, if it is "0" all calls to - * ca_context_play() will fail with CA_ERROR_DISABLED. - * - * If the list of properties is handed on to the sound server this - * property is stripped from it. - */ -#define CA_PROP_CANBERRA_ENABLE "canberra.enable" - -/** - * ca_context: - * - * A libcanberra context object. - */ -typedef struct ca_context ca_context; - -/** - * ca_finish_callback_t: - * @c: The libcanberra context this callback is called for - * @id: The numerical id passed to the ca_context_play_full() when starting the event sound playback. - * @error_code: A numerical error code describing the reason this callback is called. If CA_SUCCESS is passed in the playback of the event sound was successfully completed. - * @userdata: Some arbitrary user data the caller of ca_context_play_full() passed in. - * - * Playback completion event callback. The context this callback is - * called in is undefined, it might or might not be called from a - * background thread, and from any stack frame. The code implementing - * this function may not call any libcanberra API call from this - * callback -- this might result in a deadlock. Instead it may only be - * used to asynchronously signal some kind of notification object - * (semaphore, message queue, ...). - */ -typedef void (*ca_finish_callback_t)(ca_context *c, uint32_t id, int error_code, void *userdata); - -/** - * Error codes: - * @CA_SUCCESS: Success - * - * Error codes - */ -enum { - CA_SUCCESS = 0, - CA_ERROR_NOTSUPPORTED = -1, - CA_ERROR_INVALID = -2, - CA_ERROR_STATE = -3, - CA_ERROR_OOM = -4, - CA_ERROR_NODRIVER = -5, - CA_ERROR_SYSTEM = -6, - CA_ERROR_CORRUPT = -7, - CA_ERROR_TOOBIG = -8, - CA_ERROR_NOTFOUND = -9, - CA_ERROR_DESTROYED = -10, - CA_ERROR_CANCELED = -11, - CA_ERROR_NOTAVAILABLE = -12, - CA_ERROR_ACCESS = -13, - CA_ERROR_IO = -14, - CA_ERROR_INTERNAL = -15, - CA_ERROR_DISABLED = -16, - CA_ERROR_FORKED = -17, - CA_ERROR_DISCONNECTED = -18, - _CA_ERROR_MAX = -19 -}; - -/** - * ca_proplist: - * - * A canberra property list object. Basically a hashtable. - */ -typedef struct ca_proplist ca_proplist; - -int ca_proplist_create(ca_proplist **p); -int ca_proplist_destroy(ca_proplist *p); -int ca_proplist_sets(ca_proplist *p, const char *key, const char *value); -int ca_proplist_setf(ca_proplist *p, const char *key, const char *format, ...) __attribute__((format(printf, 3, 4))); -int ca_proplist_set(ca_proplist *p, const char *key, const void *data, size_t nbytes); - -int ca_context_create(ca_context **c); -int ca_context_set_driver(ca_context *c, const char *driver); -int ca_context_change_device(ca_context *c, const char *device); -int ca_context_open(ca_context *c); -int ca_context_destroy(ca_context *c); -int ca_context_change_props(ca_context *c, ...) __attribute__((sentinel)); -int ca_context_change_props_full(ca_context *c, ca_proplist *p); -int ca_context_play_full(ca_context *c, uint32_t id, ca_proplist *p, ca_finish_callback_t cb, void *userdata); -int ca_context_play(ca_context *c, uint32_t id, ...) __attribute__((sentinel)); -int ca_context_cache_full(ca_context *c, ca_proplist *p); -int ca_context_cache(ca_context *c, ...) __attribute__((sentinel)); -int ca_context_cancel(ca_context *c, uint32_t id); - -const char *ca_strerror(int code); - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/src/canberra.h.in b/src/canberra.h.in new file mode 100644 index 0000000..857c0cb --- /dev/null +++ b/src/canberra.h.in @@ -0,0 +1,478 @@ +#ifndef foocanberrahfoo +#define foocanberrahfoo + +/*** + This file is part of libcanberra. + + Copyright 2008 Lennart Poettering + + libcanberra is free software; you can redistribute it and/or modify + 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. + + libcanberra 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 + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with libcanberra. If not, see + . +***/ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef __GNUC__ +/* Make sure __attribute__ works on non-gcc systems. Yes, might be a bit ugly */ +#define __attribute__(x) +#endif + +/** + * CA_MAJOR: + * + * Evaluates to the major version number of libcanberra. + */ +#define CA_MAJOR (@CA_MAJOR@) + +/** + * CA_MINOR: + * + * Evaluates to the minor version number of libcanberra. + */ +#define CA_MINOR (@CA_MINOR@) + +/** + * CA_CHECK_VERSION: + * + * Evaluates to TRUE when the library version is newer than the + * specified parameters. + */ +#define CA_CHECK_VERSION(major,minor) \ + ((CA_MAJOR > (major)) || \ + (CA_MAJOR == (major) && CA_MINOR >= (minor))) + +/** + * CA_PROP_MEDIA_NAME: + * + * A name describing the media being played. Localized if possible and applicable. + */ +#define CA_PROP_MEDIA_NAME "media.name" + +/** + * CA_PROP_MEDIA_TITLE: + * + * A (song) title describing the media being played. Localized if possible and applicable. + */ +#define CA_PROP_MEDIA_TITLE "media.title" + +/** + * CA_PROP_MEDIA_ARTIST: + * + * The artist of this media. Localized if possible and applicable. + */ +#define CA_PROP_MEDIA_ARTIST "media.artist" + +/** + * CA_PROP_MEDIA_LANGUAGE: + * + * The language this media is in, in some standard POSIX locale string, such as "de_DE". + */ +#define CA_PROP_MEDIA_LANGUAGE "media.language" + +/** + * CA_PROP_MEDIA_FILENAME: + * + * The file name this media was or can be loaded from. + */ +#define CA_PROP_MEDIA_FILENAME "media.filename" + +/** + * CA_PROP_MEDIA_ICON: + * + * An icon for this media in binary PNG format. + */ +#define CA_PROP_MEDIA_ICON "media.icon" + +/** + * CA_PROP_MEDIA_ICON_NAME: + * + * An icon name as defined in the XDG icon naming specifcation. + */ +#define CA_PROP_MEDIA_ICON_NAME "media.icon_name" + +/** + * CA_PROP_MEDIA_ROLE: + * + * The "role" this media is played in. For event sounds the string + * "event". For other cases strings like "music", "video", "game", ... + */ +#define CA_PROP_MEDIA_ROLE "media.role" + +/** + * CA_PROP_EVENT_ID: + * + * A textual id for an event sound, as mandated by the XDG sound naming specification. + */ +#define CA_PROP_EVENT_ID "event.id" + +/** + * CA_PROP_EVENT_DESCRIPTION: + * + * A descriptive string for the sound event. Localized if possible and applicable. + */ +#define CA_PROP_EVENT_DESCRIPTION "event.description" + +/** + * CA_PROP_EVENT_MOUSE_X: + * + * If this sound event was triggered by a mouse input event, the X + * position of the mouse cursor on the screen, formatted as string. + */ +#define CA_PROP_EVENT_MOUSE_X "event.mouse.x" + +/** + * CA_PROP_EVENT_MOUSE_Y: + * + * If this sound event was triggered by a mouse input event, the Y + * position of the mouse cursor on the screen, formatted as string. + */ +#define CA_PROP_EVENT_MOUSE_Y "event.mouse.y" + +/** + * CA_PROP_EVENT_MOUSE_HPOS: + * + * If this sound event was triggered by a mouse input event, the X + * position of the mouse cursor as fractional value between 0 and 1, + * formatted as string, 0 reflecting the left side of the screen, 1 + * the right side. + */ +#define CA_PROP_EVENT_MOUSE_HPOS "event.mouse.hpos" + +/** + * CA_PROP_EVENT_MOUSE_VPOS: + * + * If this sound event was triggered by a mouse input event, the Y + * position of the mouse cursor as fractional value between 0 and 1, + * formatted as string, 0 reflecting the top end of the screen, 1 + * the bottom end. + */ +#define CA_PROP_EVENT_MOUSE_VPOS "event.mouse.vpos" + +/** + * CA_PROP_EVENT_MOUSE_BUTTON: + * + * If this sound event was triggered by a mouse input event, the + * number of the mouse button that triggered it, formatted as string. 1 + * for left mouse button, 3 for right, 2 for middle. + */ +#define CA_PROP_EVENT_MOUSE_BUTTON "event.mouse.button" + +/** + * CA_PROP_WINDOW_NAME: + * + * If this sound event was triggered by a window on the screen, the + * name of this window as human readable string. + */ +#define CA_PROP_WINDOW_NAME "window.name" + +/** + * CA_PROP_WINDOW_ID: + * + * If this sound event was triggered by a window on the screen, some + * identification string for this window, so that the sound system can + * recognize specific windows. + */ +#define CA_PROP_WINDOW_ID "window.id" + +/** + * CA_PROP_WINDOW_ICON: + * + * If this sound event was triggered by a window on the screen, binary + * icon data in PNG format for this window. + */ +#define CA_PROP_WINDOW_ICON "window.icon" + +/** + * CA_PROP_WINDOW_ICON_NAME: + * + * If this sound event was triggered by a window on the screen, an + * icon name for this window, as defined in the XDG icon naming + * specification. + */ +#define CA_PROP_WINDOW_ICON_NAME "window.icon_name" + +/** + * CA_PROP_WINDOW_X11_DISPLAY: + * + * If this sound event was triggered by a window on the screen and the + * windowing system is X11, the X display name of the window (e.g. ":0"). + */ +#define CA_PROP_WINDOW_X11_DISPLAY "window.x11.display" + +/** + * CA_PROP_WINDOW_X11_SCREEN: + * + * If this sound event was triggered by a window on the screen and the + * windowing system is X11, the X screen id of the window formatted as + * string (e.g. "0"). + */ +#define CA_PROP_WINDOW_X11_SCREEN "window.x11.screen" + +/** + * CA_PROP_WINDOW_X11_MONITOR: + * + * If this sound event was triggered by a window on the screen and the + * windowing system is X11, the X monitor id of the window formatted as + * string (e.g. "0"). + */ +#define CA_PROP_WINDOW_X11_MONITOR "window.x11.monitor" + +/** + * CA_PROP_WINDOW_X11_XID: + * + * If this sound event was triggered by a window on the screen and the + * windowing system is X11, the XID of the window formatted as string. + */ +#define CA_PROP_WINDOW_X11_XID "window.x11.xid" + +/** + * CA_PROP_APPLICATION_NAME: + * + * The name of the application this sound event was triggered by as + * human readable string. (e.g. "GNU Emacs") Localized if possible and + * applicable. + */ +#define CA_PROP_APPLICATION_NAME "application.name" + +/** + * CA_PROP_APPLICATION_ID: + * + * An identifier for the program this sound event was triggered + * by. (e.g. "org.gnu.emacs"). + */ +#define CA_PROP_APPLICATION_ID "application.id" + +/** + * CA_PROP_APPLICATION_VERSION: + * + * A version number for the program this sound event was triggered + * by. (e.g. "22.2") + */ +#define CA_PROP_APPLICATION_VERSION "application.version" + +/** + * CA_PROP_APPLICATION_ICON: + * + * Binary icon data in PNG format for the application this sound event + * is triggered by. + */ +#define CA_PROP_APPLICATION_ICON "application.icon" + +/** + * CA_PROP_APPLICATION_ICON_NAME: + * + * An icon name for the application this sound event is triggered by, + * as defined in the XDG icon naming specification. + */ +#define CA_PROP_APPLICATION_ICON_NAME "application.icon_name" + +/** + * CA_PROP_APPLICATION_LANGUAGE: + * + * The locale string the application that is triggering this sound + * event is running in. A POSIX locale string such as de_DE@euro. + */ +#define CA_PROP_APPLICATION_LANGUAGE "application.language" + +/** + * CA_PROP_APPLICATION_PROCESS_ID: + * + * The unix PID of the process that is triggering this sound event, formatted as string. + */ +#define CA_PROP_APPLICATION_PROCESS_ID "application.process.id" + +/** + * CA_PROP_APPLICATION_PROCESS_BINARY: + * + * The path to the process binary of the process that is triggering this sound event. + */ +#define CA_PROP_APPLICATION_PROCESS_BINARY "application.process.binary" + +/** + * CA_PROP_APPLICATION_PROCESS_USER: + * + * The user that owns the process that is triggering this sound event. + */ +#define CA_PROP_APPLICATION_PROCESS_USER "application.process.user" + +/** + * CA_PROP_APPLICATION_PROCESS_HOST: + * + * The host name of the host the process that is triggering this sound event runs on. + */ +#define CA_PROP_APPLICATION_PROCESS_HOST "application.process.host" + +/** + * CA_PROP_CANBERRA_CACHE_CONTROL: + * + * A special property that can be used to control the automatic sound + * caching of sounds in the sound server. One of "permanent", + * "volatile", "never". "permanent" will cause this sample to be + * cached in the server permanently. This is useful for very + * frequently used sound events such as those used for input + * feedback. "volatile" may be used for cacheing sounds in the sound + * server temporarily. They will expire after some time or on cache + * pressure. Finally, "never" may be used for sounds that should never + * be cached, because they are only generated very seldomly or even + * only once at most (such as desktop login sounds). + * + * If this property is not explicitly passed to ca_context_play() it + * will default to "never". If it is not explicitly passed to + * ca_context_cache() it will default to "permanent". + * + * If the list of properties is handed on to the sound server this + * property is stripped from it. + */ +#define CA_PROP_CANBERRA_CACHE_CONTROL "canberra.cache-control" + +/** + * CA_PROP_CANBERRA_VOLUME: + * + * A special property that can be used to control the volume this + * sound event is played in if the backend supports it. A floating + * point value for the decibel multiplier for the sound. 0 dB relates + * to zero gain, and is the default volume these sounds are played in. + * + * If the list of properties is handed on to the sound server this + * property is stripped from it. + */ +#define CA_PROP_CANBERRA_VOLUME "canberra.volume" + +/** + * CA_PROP_CANBERRA_XDG_THEME_NAME: + * + * A special property that can be used to control the XDG sound theme that + * is used for this sample. + * + * If the list of properties is handed on to the sound server this + * property is stripped from it. + */ +#define CA_PROP_CANBERRA_XDG_THEME_NAME "canberra.xdg-theme.name" + +/** + * CA_PROP_CANBERRA_XDG_THEME_OUTPUT_PROFILE: + * + * A special property that can be used to control the XDG sound theme + * output profile that is used for this sample. + * + * If the list of properties is handed on to the sound server this + * property is stripped from it. + */ +#define CA_PROP_CANBERRA_XDG_THEME_OUTPUT_PROFILE "canberra.xdg-theme.output-profile" + +/** + * CA_PROP_CANBERRA_ENABLE: + * + * A special property that can be used to control whether any sounds + * are played at all. If this property is "1" or unset sounds are + * played as normal. However, if it is "0" all calls to + * ca_context_play() will fail with CA_ERROR_DISABLED. + * + * If the list of properties is handed on to the sound server this + * property is stripped from it. + */ +#define CA_PROP_CANBERRA_ENABLE "canberra.enable" + +/** + * ca_context: + * + * A libcanberra context object. + */ +typedef struct ca_context ca_context; + +/** + * ca_finish_callback_t: + * @c: The libcanberra context this callback is called for + * @id: The numerical id passed to the ca_context_play_full() when starting the event sound playback. + * @error_code: A numerical error code describing the reason this callback is called. If CA_SUCCESS is passed in the playback of the event sound was successfully completed. + * @userdata: Some arbitrary user data the caller of ca_context_play_full() passed in. + * + * Playback completion event callback. The context this callback is + * called in is undefined, it might or might not be called from a + * background thread, and from any stack frame. The code implementing + * this function may not call any libcanberra API call from this + * callback -- this might result in a deadlock. Instead it may only be + * used to asynchronously signal some kind of notification object + * (semaphore, message queue, ...). + */ +typedef void (*ca_finish_callback_t)(ca_context *c, uint32_t id, int error_code, void *userdata); + +/** + * Error codes: + * @CA_SUCCESS: Success + * + * Error codes + */ +enum { + CA_SUCCESS = 0, + CA_ERROR_NOTSUPPORTED = -1, + CA_ERROR_INVALID = -2, + CA_ERROR_STATE = -3, + CA_ERROR_OOM = -4, + CA_ERROR_NODRIVER = -5, + CA_ERROR_SYSTEM = -6, + CA_ERROR_CORRUPT = -7, + CA_ERROR_TOOBIG = -8, + CA_ERROR_NOTFOUND = -9, + CA_ERROR_DESTROYED = -10, + CA_ERROR_CANCELED = -11, + CA_ERROR_NOTAVAILABLE = -12, + CA_ERROR_ACCESS = -13, + CA_ERROR_IO = -14, + CA_ERROR_INTERNAL = -15, + CA_ERROR_DISABLED = -16, + CA_ERROR_FORKED = -17, + CA_ERROR_DISCONNECTED = -18, + _CA_ERROR_MAX = -19 +}; + +/** + * ca_proplist: + * + * A canberra property list object. Basically a hashtable. + */ +typedef struct ca_proplist ca_proplist; + +int ca_proplist_create(ca_proplist **p); +int ca_proplist_destroy(ca_proplist *p); +int ca_proplist_sets(ca_proplist *p, const char *key, const char *value); +int ca_proplist_setf(ca_proplist *p, const char *key, const char *format, ...) __attribute__((format(printf, 3, 4))); +int ca_proplist_set(ca_proplist *p, const char *key, const void *data, size_t nbytes); + +int ca_context_create(ca_context **c); +int ca_context_set_driver(ca_context *c, const char *driver); +int ca_context_change_device(ca_context *c, const char *device); +int ca_context_open(ca_context *c); +int ca_context_destroy(ca_context *c); +int ca_context_change_props(ca_context *c, ...) __attribute__((sentinel)); +int ca_context_change_props_full(ca_context *c, ca_proplist *p); +int ca_context_play_full(ca_context *c, uint32_t id, ca_proplist *p, ca_finish_callback_t cb, void *userdata); +int ca_context_play(ca_context *c, uint32_t id, ...) __attribute__((sentinel)); +int ca_context_cache_full(ca_context *c, ca_proplist *p); +int ca_context_cache(ca_context *c, ...) __attribute__((sentinel)); +int ca_context_cancel(ca_context *c, uint32_t id); + +const char *ca_strerror(int code); + +#ifdef __cplusplus +} +#endif + +#endif -- cgit