API Guide Home (Online version only) |

# TonesLibTypes.h

Go to the documentation of this file.

    00001 /*******************************************************************************
    00002  * Copyright (c) 2004-2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  ******************************************************************************/
    00005 /**
    00006  * @defgroup    Tone Ring Tone Library
    00007  * @brief       This library provides support for application that wants to
    00008  *              manage or play ring tones from within the application itself.
    00009  *
    00010  * Applications that wish to play, manage or create ring tones from within the
    00011  * application themselves can use the APIs provided by this library. This library
    00012  * can also be used to set different ring tones preferences that are used by
    00013  * the system when there is, for example, an incoming call, email or sms alert, etc.
    00014  *
    00015  * The calling application should always load this library with
    00016  * SysLibLoad() before use, even if it is already open by another
    00017  * application(ie, SysLibFind() returns a valid refnum). When
    00018  * the application is done with the library, it should be
    00019  * unloaded with SysLibRemove(). We do this because there is
    00020  * no good way to synchronize loading and unloading of libraries
    00021  * among multiple applications. It also greatly simplifies internal
    00022  * synchronization.
    00023  *
    00024  * @{
    00025  * @}
    00026  */
    00027 /**
    00028  * @ingroup Tone
    00029  */
    00030
    00031 /**
    00032  * @file    TonesLibTypes.h
    00033  * @brief   Public 68K header file for the Ring Tone library on Treo devices.
    00034  *
    00035  * This file contains the common constants for the tones and also the structure
    00036  * that contains the ring-tone related sound preferences.
    00037  * <hr>
    00038  */
    00039
    00040 #ifndef TONES_LIB_TYPES__H__
    00041 #define TONES_LIB_TYPES__H__
    00042
    00043 #define      tonesLibName           "Tones Library" /**<Name of the Tone Types library. */
    00044 #define      tonesLibCreator        hsFileCTonesLib /**<Creator ID of the Tone Types library. */
    00045 #define      tonesLibType           sysFileTLibrary /**<Type of the Tone Types library. */
    00046
    00047 #define      kMaxTonesNameSize       32 /**<Maximum size of a tone name. */
    00048 #define       tonesLibPlayForever     0xFFFF /**<Used to play a tone over and over indefinitely. */
    00049
    00050 /**
    00051  * @name Error Codes
    00052  *
    00053  */
    00054 /*@{*/
    00055 #define      tonesLibErrClass        0x9000 /**<No definition. */
    00056 #define      tonesLibErrCreateDBFailed  tonesLibErrClass | 1/**<No definition. */
    00057 #define      tonesLibErrNoMemory        tonesLibErrClass | 2/**<No definition. */
    00058 #define      tonesLibErrNoTone          tonesLibErrClass | 3/**<No definition. */
    00059 #define      tonesLibErrDBNotFound      tonesLibErrClass | 4/**<No definition. */
    00060 #define      tonesLibErrDBWriteFailed   tonesLibErrClass | 5/**<No definition. */
    00061 #define      tonesLibErrUserCancel      tonesLibErrClass | 6/**<No definition. */
    00062 #define      tonesLibErrBadParams       tonesLibErrClass  | 7/**<No definition. */
    00063 #define      tonesLibErrUnknown         tonesLibErrClass | 8/**<No definition. */
    00064 #define      tonesLibErrNotAllowed       tonesLibErrClass | 9/**<No definition. */
    00065 #define      tonesLibErrAlreadyPlaying       tonesLibErrClass | 10/**<No definition. */
    00066 /*@}*/
    00067
    00068 /**
    00069  * @name Utility Macros
    00070  *
    00071  */
    00072 /*@{*/
    00073 #define      CompareToneIdentifiers(tone1, tone2) \
    00074              (tone1.id == tone2.id && tone1.toneType == tone2.toneType)/**<No definition. */
    00075 #define      CopyToneIdentifier(destP, src) \
    00076              destP->id = src.id; \
    00077              destP->toneType = src.toneType/**<No definition. */
    00078 #define      CopyMIDIToneIdentifier(destP, src) \
    00079              destP->id = src; \
    00080              destP->toneType = toneTypeMIDI/**<No definition. */
    00081 /*@}*/
    00082
    00083 /**
    00084  * Tone types
    00085  */
    00086 enum _ToneType {
    00087     toneTypeMIDI,         /**<Record in MIDI Ring Tones DB. */
    00088     toneTypeWAV,          /**<WAV in a SndFileStream. */
    00089     toneTypeAMR,          /**<AMR in a SndFIleStream. */
    00090     toneTypeSystemSound,  /**<Unused. */
    00091     toneTypeQCELP,        /**<QCELP in a SndFileStream. */
    00092     toneTypeMP3,          /**<MP3 in a SndFileStream */
    00093     toneTypeAAC           /**<AAC in a SndFileStream */
    00094 };
    00095
    00096 /** Holds tone type value */
    00097 typedef UInt16 ToneType;
    00098
    00099 /**
    00100  * Sound preferences type
    00101  */
    00102 enum _SoundPrefType
    00103 {
    00104   soundPrefTypePhone,           /**<Tone pref for phone. */
    00105   soundPrefTypeEmail,           /**<Tone pref for email. */
    00106   soundPrefTypeCalendar,        /**<Tone pref for Calendar. */
    00107   soundPrefTypeIM,              /**<Tone pref for IM. */
    00108   soundPrefTypeMMS,             /**<Tone pref for MMS. */
    00109   soundPrefTypeSMS,             /**<Tone pref for SMS. */
    00110   soundPrefTypeNetworkSounds,   /**<Tone pref for SMS. */
    00111   soundPrefTypeLast             /**<Last item in enum. Please keep it as last item. */
    00112 };
    00113
    00114 /** Holds sound preference type value */
    00115 typedef UInt16  SoundPrefType;
    00116
    00117 /**
    00118  * Tone volume
    00119  */
    00120 enum _ToneVolume
    00121 {
    00122   toneVolumeOff,    /**<Volume off */
    00123   toneVolume1,      /**<Volume level 1 */
    00124   toneVolume2,      /**<Volume level 2 */
    00125   toneVolume3,      /**<Volume level 3 */
    00126   toneVolume4,      /**<Volume level 4 */
    00127   toneVolume5,      /**<Volume level 5 */
    00128   toneVolume6,      /**<Volume level 6 */
    00129   toneVolume7       /**<Volume level 7 */
    00130 };
    00131
    00132 /** Holds tone volume value */
    00133 typedef UInt16  ToneVolume;
    00134
    00135 /**
    00136  * Number of times to play tone
    00137  */
    00138 enum _TonePlayNumberTimes
    00139 {
    00140   tonePlayOnce,     /**<Play once. */
    00141   tonePlayTwice,    /**<Play twice. */
    00142   tonePlay3Times,   /**<Play three times. */
    00143   tonePlay5Times,   /**<Play five times. */
    00144   tonePlay10Times,  /**<Play ten times. */
    00145   tonePlay100Times  /**<Play one hundred times. */
    00146 };
    00147
    00148 /** Holds number of times to play a tone value */
    00149 typedef UInt8 TonePlayNumberTimes;
    00150
    00151 /**
    00152  * Tone repeat interval
    00153  */
    00154 enum _ToneRepeatInterval
    00155 {
    00156   toneRepeatEveryMinute,    /**<Repeat every minute. */
    00157   toneRepeatEvery5Minutes,  /**<Repeat every 5 minutes. */
    00158   toneRepeatEvery10Minutes, /**<Repeat every 10 minutes. */
    00159   toneRepeatEvery30Minutes  /**<Repeat every 30 minutes. */
    00160 };
    00161
    00162 /** Holds the tone repeat interval value */
    00163 typedef UInt8 ToneRepeatInterval;
    00164
    00165 /**
    00166  * Tone time unit
    00167  */
    00168 enum _ToneTimeUnit
    00169 {
    00170   toneTimeUnitMinutes,   /**< Minutes */
    00171   toneTimeUnitHours,     /**< Hours */
    00172   toneTimeUnitDays       /**< Days  */
    00173
    00174 };
    00175
    00176 /** Holds the tone time unit value */
    00177 typedef UInt8 ToneTimeUnit;
    00178
    00179 /**
    00180  * Tone vibrate type
    00181  */
    00182 enum _ToneVibrateType
    00183 {
    00184   toneVibrateNone,      /**< None */
    00185   toneVibrateRing,      /**< Phone ring event */
    00186   toneVibrateAlert,     /**< Alert event */
    00187   toneVibrateMail,      /**< New mail */
    00188   toneVibrateCalender,  /**< Calendar event */
    00189   toneVibrateSMS,       /**< New SMS */
    00190   toneVibrateVoicemail, /**< New Voicemail */
    00191   toneVibrateThenRing,  /**< Phone vibrate-then-ring event */
    00192
    00193   /* We are reserving the upper 2 bits in the ToneVibrateType for tone interrupt mode information */
    00194   toneInterruptPhone = 64,  /**< Interrupt mode for phone '01' in upper two bits */
    00195   toneInterruptMode2 = 128, /**< Reserved interrupt mode  '10' in upper two bits */
    00196   toneInterruptMode3 = 192, /**< Reserved interrupt mode  '11' in upper two bits */
    00197 };
    00198
    00199 #define toneInterruptMask 0x00C0
    00200
    00201 /** Holds the tone vibrate type value */
    00202 typedef UInt8 ToneVibrateType;
    00203
    00204 /**
    00205  * @brief No definition.
    00206  */
    00207 typedef struct {
    00208     UInt32 id;          /**<Tone ID */
    00209     ToneType toneType;  /**<Tony Type (AMR, MIDI, etc). @see ToneType */
    00210 } ToneIdentifier;
    00211
    00212 /**
    00213  * @brief Tone characteristics
    00214  */
    00215 typedef struct {
    00216
    00217     Char   name [kMaxTonesNameSize];  /**<Name of the ring tone.  */
    00218     ToneIdentifier identifier;  /**<Unique ID for the ring tone.  */
    00219     Boolean protectedTone;   /**<Whether Tone is protected and cannot be beamed or sent.  */
    00220
    00221 } ToneItemType, * ToneItemPtr;
    00222
    00223 /**
    00224  * @brief  Structure for IM Sound Pref.
    00225  */
    00226 typedef struct {
    00227
    00228     ToneIdentifier chatTone;    /**<Tone used for chatting */
    00229     ToneIdentifier messageTone; /**<Tone used for messaging */
    00230
    00231 } SoundPreferenceIM;
    00232
    00233 /**
    00234  * @brief  Structure for Phone Sound Pref.
    00235  */
    00236 typedef struct {
    00237     ToneIdentifier unknownCallerTone;   /**<Tone used when caller is unknown */
    00238     ToneIdentifier knownCallerTone;     /**<Tone used when caller is known */
    00239     ToneIdentifier roamingTone;         /**<Tone used when roaming */
    00240     ToneIdentifier  voicemailTone;      /**<Tone used for incoming voicemail */
    00241     Boolean serviceTone;                /**<No definition. */
    00242 } SoundPreferencePhone;
    00243
    00244 /**
    00245  * @brief  Structure for Email Sound Pref.
    00246  */
    00247 typedef struct {
    00248     ToneIdentifier alertTone;   /**<Tone used for new email alert */
    00249     Boolean newMailAlert;       /**<Play tone if true */
    00250 } SoundPreferenceEmail;
    00251
    00252 /**
    00253  * @brief  Structure for Calendar Sound Pref.
    00254  */
    00255 typedef struct {
    00256     ToneIdentifier alarmTone;               /**<Tone used for alarm */
    00257     ToneIdentifier reminderTone;            /**<Tone used for event reminder */
    00258     TonePlayNumberTimes playSoundTimes;     /**<Number of times tone should be played */
    00259     TonePlayNumberTimes repeatAlarmTimes;   /**<Number of time alarm should be repeated */
    00260     ToneRepeatInterval repeatInterval;      /**<Alarm repeat interval */
    00261     UInt16 presetTime;                      /**<Alarm preset time */
    00262     ToneTimeUnit presetTimeUnit;            /**<Alarm preset time unit (minute, hour, day) */
    00263     Boolean alarmPreset;                    /**<Preset alarm if true */
    00264 } SoundPreferenceCalendar;
    00265
    00266 /**
    00267  * @brief  Structure for SMS Sound Pref.
    00268  */
    00269 typedef struct {
    00270     ToneIdentifier messageTone; /**<Tone used for SMS */
    00271     Boolean privacy;            /**<No definition. */
    00272     Boolean msgAlert;           /**<If true, alert when new SMS arrives */
    00273     Boolean rcptAlert;          /**<If true, alert when recipient receives SMS */
    00274 } SoundPreferenceSMS;
    00275
    00276 /**
    00277  * @brief  Structure for MMS Sound Pref.
    00278  */
    00279 typedef struct {
    00280   ToneIdentifier messageTone;   /**<Tone used when MMS arrives*/
    00281 } SoundPreferenceMMS;
    00282
    00283 /**
    00284  * @brief  Structure for network related sounds.
    00285  */
    00286 typedef struct {
    00287     Boolean signalFadedTone;
    00288     Boolean eriStatusTone;
    00289 } SoundPreferenceNetworkSounds;
    00290
    00291
    00292 /**
    00293  * @brief  Structure containing all the Sound Preference data.
    00294  */
    00295 typedef struct {
    00296     /** union of various sound preferences */
    00297     union _tonePrefs
    00298       {
    00299         SoundPreferenceIM imSoundPrefs;                     /**<No definition. */
    00300         SoundPreferencePhone phoneSoundPrefs;               /**<No definition. */
    00301         SoundPreferenceEmail emailSoundPrefs;               /**<No definition. */
    00302         SoundPreferenceCalendar calendarSoundPrefs;         /**<No definition. */
    00303         SoundPreferenceSMS  smsSoundPrefs;                  /**<No definition. */
    00304         SoundPreferenceMMS  mmsSoundPrefs;                  /**<No definition. */
    00305         SoundPreferenceNetworkSounds  networkSoundPrefs;    /**<No definition. */
    00306       } tonePrefs;                                          /**<Holds data for various Sound Prefs */
    00307     ToneVolume soundOnVolume;                               /**<Volume of tone */
    00308     Boolean soundOnVibrate;                                 /**<No definition. */
    00309     Boolean soundOffVibrate;                                /**<No definition. */
    00310 } SoundPreference;
    00311
    00312 #define kTonesDialogFlagNonModal      0x00000001    /**<Hides the Done button from the play tone dialog. */
    00313
    00314 /**
    00315  * @name Function Traps
    00316  *
    00317  */
    00318 /*@{*/
    00319 #define       tonesLibTrapGetToneList  sysLibTrapCustom /**<Trap ID for the function that gets the tone list. */
    00320 #define       tonesLibTrapGetToneIDs    sysLibTrapCustom+1/**<Trap ID for the function that gets the list of tone ids. */
    00321 #define       tonesLibTrapGetToneName   sysLibTrapCustom+2/**<Trap ID for the function that gets the name of a tone. */
    00322 #define       tonesLibTrapPlayTone      sysLibTrapCustom+3/**<Trap ID for the function that plays a tone. */
    00323 #define       tonesLibTrapAddMidiTone       sysLibTrapCustom+4/**<Trap ID for the function to add a MIDI tone.
    00324   Note: This used to be tonesLibTrapAddTone. Leaving this
    00325           trap number maintains binary compatability with existing
    00326           applications. Recompiling older source code will fail since
    00327           the new version of TonesLibAddTone takes toneType as
    00328           an additional parameter. */
    00329 #define       tonesLibTrapManageTones       sysLibTrapCustom+5/**<Trap ID for function to manage tones. */
    00330 #define       tonesLibTrapDeleteTone       sysLibTrapCustom+6/**<Trap ID for function to delete a tone. */
    00331 #define       tonesLibTrapGetSoundPrefs     sysLibTrapCustom+7/**<Trap ID for function to get a sound preference. */
    00332 #define       tonesLibTrapSetSoundPrefs     sysLibTrapCustom+8/**<Trap ID for function to set a sound preference. */
    00333 #define       tonesLibTrapInitTonesDB       sysLibTrapCustom+9/**<Trap ID for function to initialize the Tones database. */
    00334 #define       tonesLibTrapPickTone          sysLibTrapCustom+10/**<Trap ID for function to pick a tone to attach. */
    00335 #define       tonesLibTrapStopTone          sysLibTrapCustom+11/**<Trap ID for function to stop the playback of the current tone. */
    00336 #define       tonesLibTrapGetSoundOnVolume  sysLibTrapCustom+12/**<Trap ID for function to get the on volume of a sound type. */
    00337 #define       tonesLibTrapSetSoundOnVolume  sysLibTrapCustom+13/**<Trap ID for function to set the on volume of a sound type. */
    00338 #define       tonesLibTrapDoDialog          sysLibTrapCustom+14/**<Trap ID for function to display the tones list. */
    00339 #define       tonesLibTrapGetToneSize       sysLibTrapCustom+15/**<Trap ID for function to get the size of a tone. */
    00340 #define       tonesLibTrapToneCreate        sysLibTrapCustom+16/**<Trap ID for function to begin adding a new tone. */
    00341 #define       tonesLibTrapToneWrite         sysLibTrapCustom+17/**<Trap ID for function to write data to a new tone. */
    00342 #define       tonesLibTrapToneClose         sysLibTrapCustom+18/**<Trap ID for function to finish adding a new tone. */
    00343 #define       tonesLibTrapToneRecord        sysLibTrapCustom+19/**<Trap ID for function to record a new tone. */
    00344 #define       tonesLibTrapEscalateRingTones sysLibTrapCustom+20/**<Trap ID for function to set/query ringtone escalation. */
    00345 #define       tonesLibTrapPlayRingTone      sysLibTrapCustom+21/**<Trap ID for function to play a ringtone. */
    00346 #define       tonesLibTrapSaveUndeletableTones      sysLibTrapCustom+22 /**<Trap ID for function to create backup db. */
    00347 #define       tonesLibTrapCopyBackUndeletableTones  sysLibTrapCustom+23 /**<Trap ID for function to copy undeletable tones back. */
    00348
    00349 /*@}*/
    00350
    00351 #endif  // TONES_LIB_TYPES__H__
    00352

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:55 2008 for Palm API Guide