libpurple/sound.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_SOUND_H
  23 #define PURPLE_SOUND_H
  24 /**
  25  * SECTION:sound
  26  * @section_id: libpurple-sound
  27  * @short_description: Sound subsystem definition.
  28  * @title: Sound API
  29  * @see_also: <link linkend="chapter-signals-sound">Sound signals</link>
  30  */
  31
  32 #include "account.h"
  33
  34 #define PURPLE_TYPE_SOUND_UI_OPS (purple_sound_ui_ops_get_type())
  35
  36 /**************************************************************************/
  37 /* Data Structures                                                        */
  38 /**************************************************************************/
  39 typedef struct _PurpleSoundUiOps PurpleSoundUiOps;
  40
  41 /**
  42  * PurpleSoundStatus:
  43  * @PURPLE_SOUND_STATUS_AVAILABLE:      Only play sound when Status is Available.
  44  * @PURPLE_SOUND_STATUS_AWAY:           Only play sound when Status is Not Available.
  45  * @PURPLE_SOUND_STATUS_ALWAYS:         Always play sound.
  46  *
  47  * A preference option on when to play sounds depending on the current status
  48  */
  49 typedef enum {
  50         PURPLE_SOUND_STATUS_AVAILABLE = 1,
  51         PURPLE_SOUND_STATUS_AWAY,
  52         PURPLE_SOUND_STATUS_ALWAYS,
  53 } PurpleSoundStatus;
  54
  55 /**
  56  * PurpleSoundEventID:
  57  * @PURPLE_SOUND_BUDDY_ARRIVE:   Buddy signs on.
  58  * @PURPLE_SOUND_BUDDY_LEAVE:    Buddy signs off.
  59  * @PURPLE_SOUND_RECEIVE:        Receive an IM.
  60  * @PURPLE_SOUND_FIRST_RECEIVE:  Receive an IM that starts a conv.
  61  * @PURPLE_SOUND_SEND:           Send an IM.
  62  * @PURPLE_SOUND_CHAT_JOIN:      Someone joins a chat.
  63  * @PURPLE_SOUND_CHAT_LEAVE:     Someone leaves a chat.
  64  * @PURPLE_SOUND_CHAT_YOU_SAY:   You say something in a chat.
  65  * @PURPLE_SOUND_CHAT_SAY:       Someone else says somthing in a chat.
  66  * @PURPLE_SOUND_POUNCE_DEFAULT: Default sound for a buddy pounce.
  67  * @PURPLE_SOUND_CHAT_NICK:      Someone says your name in a chat.
  68  * @PURPLE_SOUND_GOT_ATTENTION:  Got an attention.
  69  * @PURPLE_NUM_SOUNDS:           Total number of sounds.
  70  *
  71  * A type of sound.
  72  */
  73 typedef enum
  74 {
  75         PURPLE_SOUND_BUDDY_ARRIVE = 0,
  76         PURPLE_SOUND_BUDDY_LEAVE,
  77         PURPLE_SOUND_RECEIVE,
  78         PURPLE_SOUND_FIRST_RECEIVE,
  79         PURPLE_SOUND_SEND,
  80         PURPLE_SOUND_CHAT_JOIN,
  81         PURPLE_SOUND_CHAT_LEAVE,
  82         PURPLE_SOUND_CHAT_YOU_SAY,
  83         PURPLE_SOUND_CHAT_SAY,
  84         PURPLE_SOUND_POUNCE_DEFAULT,
  85         PURPLE_SOUND_CHAT_NICK,
  86         PURPLE_SOUND_GOT_ATTENTION,
  87         PURPLE_NUM_SOUNDS
  88
  89 } PurpleSoundEventID;
  90
  91 /**
  92  * PurpleSoundUiOps:
  93  * @init: Called when the UI should initialize sound
  94  * @uninit: Called when the UI should teardown sound
  95  * @play_file: Called when a file should be played.
  96  *             <sbr/>@filename: The filename to play
  97  * @play_event: Called when a sound event should be played.
  98  *              <sbr/>@event: The #@PurpleSoundEventID to play
  99  *
 100  * Operations used by the core to request that particular sound files, or the
 101  * sound associated with a particular event, should be played.
 102  */
 103 struct _PurpleSoundUiOps
 104 {
 105         void (*init)(void);
 106         void (*uninit)(void);
 107         void (*play_file)(const char *filename);
 108         void (*play_event)(PurpleSoundEventID event);
 109
 110         /*< private >*/
 111         void (*_purple_reserved1)(void);
 112         void (*_purple_reserved2)(void);
 113         void (*_purple_reserved3)(void);
 114         void (*_purple_reserved4)(void);
 115 };
 116
 117 G_BEGIN_DECLS
 118
 119 /**************************************************************************/
 120 /* Sound API                                                              */
 121 /**************************************************************************/
 122
 123 /**
 124  * purple_sound_ui_ops_get_type:
 125  *
 126  * Returns: The #GType for the #PurpleSoundUiOps boxed structure.
 127  */
 128 GType purple_sound_ui_ops_get_type(void);
 129
 130 /**
 131  * purple_sound_play_file:
 132  * @filename: The file to play.
 133  * @account: (nullable): The account that this sound is associated with, or
 134  *        NULL if the sound is not associated with any specific
 135  *        account.  This is needed for the "sounds while away?"
 136  *        preference to work correctly.
 137  *
 138  * Plays the specified sound file.
 139  */
 140 void purple_sound_play_file(const char *filename, PurpleAccount *account);
 141
 142 /**
 143  * purple_sound_play_event:
 144  * @event: The event.
 145  * @account: (nullable): The account that this sound is associated with, or
 146  *        NULL if the sound is not associated with any specific
 147  *        account.  This is needed for the "sounds while away?"
 148  *        preference to work correctly.
 149  *
 150  * Plays the sound associated with the specified event.
 151  */
 152 void purple_sound_play_event(PurpleSoundEventID event, PurpleAccount *account);
 153
 154 /**
 155  * purple_sound_set_ui_ops:
 156  * @ops: The UI sound operations structure.
 157  *
 158  * Sets the UI sound operations
 159  */
 160 void purple_sound_set_ui_ops(PurpleSoundUiOps *ops);
 161
 162 /**
 163  * purple_sound_get_ui_ops:
 164  *
 165  * Gets the UI sound operations
 166  *
 167  * Returns: The UI sound operations structure.
 168  */
 169 PurpleSoundUiOps *purple_sound_get_ui_ops(void);
 170
 171 /**
 172  * purple_sound_init:
 173  *
 174  * Initializes the sound subsystem
 175  */
 176 void purple_sound_init(void);
 177
 178 /**
 179  * purple_sound_uninit:
 180  *
 181  * Shuts down the sound subsystem
 182  */
 183 void purple_sound_uninit(void);
 184
 185 /**
 186  * purple_sounds_get_handle:
 187  *
 188  * Returns the sound subsystem handle.
 189  *
 190  * Returns: The sound subsystem handle.
 191  */
 192 void *purple_sounds_get_handle(void);
 193
 194 G_END_DECLS
 195
 196 #endif /* PURPLE_SOUND_H */