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_SOUND_GOT_ATTENTION,        /**< Got an attention                                          */
  55         PURPLE_NUM_SOUNDS              /**< Total number of sounds.               */
  56
  57 } PurpleSoundEventID;
  58
  59 /** Operations used by the core to request that particular sound files, or the
  60  *  sound associated with a particular event, should be played.
  61  */
  62 typedef struct _PurpleSoundUiOps
  63 {
  64         void (*init)(void);
  65         void (*uninit)(void);
  66         void (*play_file)(const char *filename);
  67         void (*play_event)(PurpleSoundEventID event);
  68
  69         void (*_purple_reserved1)(void);
  70         void (*_purple_reserved2)(void);
  71         void (*_purple_reserved3)(void);
  72         void (*_purple_reserved4)(void);
  73 } PurpleSoundUiOps;
  74
  75 #ifdef __cplusplus
  76 extern "C" {
  77 #endif
  78
  79 /**************************************************************************/
  80 /** @name Sound API                                                       */
  81 /**************************************************************************/
  82 /*@{*/
  83
  84 /**
  85  * Plays the specified sound file.
  86  *
  87  * @param filename The file to play.
  88  * @param account The account that this sound is associated with, or
  89  *        NULL if the sound is not associated with any specific
  90  *        account.  This is needed for the "sounds while away?"
  91  *        preference to work correctly.
  92  */
  93 void purple_sound_play_file(const char *filename, const PurpleAccount *account);
  94
  95 /**
  96  * Plays the sound associated with the specified event.
  97  *
  98  * @param event The event.
  99  * @param account The account that this sound is associated with, or
 100  *        NULL if the sound is not associated with any specific
 101  *        account.  This is needed for the "sounds while away?"
 102  *        preference to work correctly.
 103  */
 104 void purple_sound_play_event(PurpleSoundEventID event, const PurpleAccount *account);
 105
 106 /**
 107  * Sets the UI sound operations
 108  *
 109  * @param ops The UI sound operations structure.
 110  */
 111 void purple_sound_set_ui_ops(PurpleSoundUiOps *ops);
 112
 113 /**
 114  * Gets the UI sound operations
 115  *
 116  * @return The UI sound operations structure.
 117  */
 118 PurpleSoundUiOps *purple_sound_get_ui_ops(void);
 119
 120 /**
 121  * Initializes the sound subsystem
 122  */
 123 void purple_sound_init(void);
 124
 125 /**
 126  * Shuts down the sound subsystem
 127  */
 128 void purple_sound_uninit(void);
 129
 130 /**
 131  * Returns the sound subsystem handle.
 132  *
 133  * @return The sound subsystem handle.
 134  */
 135 void *purple_sounds_get_handle(void);
 136
 137 /*@}*/
 138
 139 #ifdef __cplusplus
 140 }
 141 #endif
 142
 143 #endif /* _PURPLE_SOUND_H_ */