libpurple/sound.h

   1 /**
   2  * @file sound.h Sound API
   3  * @ingroup core
   4  * @see @ref sound-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef _PURPLE_SOUND_H_
  28 #define _PURPLE_SOUND_H_
  29
  30 #include "account.h"
  31
  32 /**************************************************************************/
  33 /** Data Structures                                                       */
  34 /**************************************************************************/
  35
  36
  37 /**
  38  * A type of sound.
  39  */
  40
  41 typedef enum _PurpleSoundEventID
  42 {
  43         PURPLE_SOUND_BUDDY_ARRIVE = 0, /**< Buddy signs on.                       */
  44         PURPLE_SOUND_BUDDY_LEAVE,      /**< Buddy signs off.                      */
  45         PURPLE_SOUND_RECEIVE,          /**< Receive an IM.                        */
  46         PURPLE_SOUND_FIRST_RECEIVE,    /**< Receive an IM that starts a conv.     */
  47         PURPLE_SOUND_SEND,             /**< Send an IM.                           */
  48         PURPLE_SOUND_CHAT_JOIN,        /**< Someone joins a chat.                 */
  49         PURPLE_SOUND_CHAT_LEAVE,       /**< Someone leaves a chat.                */
  50         PURPLE_SOUND_CHAT_YOU_SAY,     /**< You say something in a chat.          */
  51         PURPLE_SOUND_CHAT_SAY,         /**< Someone else says somthing in a chat. */
  52         PURPLE_SOUND_POUNCE_DEFAULT,   /**< Default sound for a buddy pounce.     */
  53         PURPLE_SOUND_CHAT_NICK,        /**< Someone says your name in a chat.     */
  54         PURPLE_NUM_SOUNDS              /**< Total number of sounds.               */
  55
  56 } PurpleSoundEventID;
  57
  58 /** Operations used by the core to request that particular sound files, or the
  59  *  sound associated with a particular event, should be played.
  60  */
  61 typedef struct _PurpleSoundUiOps
  62 {
  63         void (*init)(void);
  64         void (*uninit)(void);
  65         void (*play_file)(const char *filename);
  66         void (*play_event)(PurpleSoundEventID event);
  67
  68         void (*_purple_reserved1)(void);
  69         void (*_purple_reserved2)(void);
  70         void (*_purple_reserved3)(void);
  71         void (*_purple_reserved4)(void);
  72 } PurpleSoundUiOps;
  73
  74 #ifdef __cplusplus
  75 extern "C" {
  76 #endif
  77
  78 /**************************************************************************/
  79 /** @name Sound API                                                       */
  80 /**************************************************************************/
  81 /*@{*/
  82
  83 /**
  84  * Plays the specified sound file.
  85  *
  86  * @param filename The file to play.
  87  * @param account The account that this sound is associated with, or
  88  *        NULL if the sound is not associated with any specific
  89  *        account.  This is needed for the "sounds while away?"
  90  *        preference to work correctly.
  91  */
  92 void purple_sound_play_file(const char *filename, const PurpleAccount *account);
  93
  94 /**
  95  * Plays the sound associated with the specified event.
  96  *
  97  * @param event The event.
  98  * @param account The account that this sound is associated with, or
  99  *        NULL if the sound is not associated with any specific
 100  *        account.  This is needed for the "sounds while away?"
 101  *        preference to work correctly.
 102  */
 103 void purple_sound_play_event(PurpleSoundEventID event, const PurpleAccount *account);
 104
 105 /**
 106  * Sets the UI sound operations
 107  *
 108  * @param ops The UI sound operations structure.
 109  */
 110 void purple_sound_set_ui_ops(PurpleSoundUiOps *ops);
 111
 112 /**
 113  * Gets the UI sound operations
 114  *
 115  * @return The UI sound operations structure.
 116  */
 117 PurpleSoundUiOps *purple_sound_get_ui_ops(void);
 118
 119 /**
 120  * Initializes the sound subsystem
 121  */
 122 void purple_sound_init(void);
 123
 124 /**
 125  * Shuts down the sound subsystem
 126  */
 127 void purple_sound_uninit(void);
 128
 129 /**
 130  * Returns the sound subsystem handle.
 131  *
 132  * @return The sound subsystem handle.
 133  */
 134 void *purple_sounds_get_handle(void);
 135
 136 /*@}*/
 137
 138 #ifdef __cplusplus
 139 }
 140 #endif
 141
 142 #endif /* _PURPLE_SOUND_H_ */