API Guide Home (Online version only) |

# TonesLib.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup Tone
    00007  *
    00008  */
    00009
    00010 /**
    00011  * @file   TonesLib.h
    00012  * @brief  Public 68K include file that controls the MIDI tones on a device.
    00013  *
    00014  * Notes:
    00015  *
    00016  * The calling application should always load this library with
    00017  * SysLibLoad() before use, even if it is already open by another
    00018  * application(ie, SysLibFind() returns a valid refnum). When
    00019  * the application is done with the library, it should be
    00020  * unloaded with SysLibRemove(). We do this because there is
    00021  * no good way to synchronize loading and unloading of libraries
    00022  * among multiple applications. It also greatly simplifies internal
    00023  * synchronization.
    00024  */
    00025
    00026 #ifndef __TONESLIB__H__
    00027 #define __TONESLIB__H__
    00028
    00029 #ifdef __cplusplus
    00030 extern "C" {
    00031 #endif
    00032
    00033 /// Minimum db version of TonesLibrary database that implements escalation
    00034 /// Done this way since we have no GetLibVersion() API.
    00035 #define kTonesLibVersionEscalation  10
    00036
    00037 /// Open and initialize the Tones library instance.
    00038 ///
    00039 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00040 /// @return Library error code.
    00041 Err TonesLibOpen (UInt16 refNum)
    00042                  SYS_TRAP (sysLibTrapOpen);
    00043
    00044 /// Close the Tones library instance.
    00045 ///
    00046 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00047 /// @return Library error code.
    00048 Err TonesLibClose (UInt16 refNum)
    00049                  SYS_TRAP (sysLibTrapClose);
    00050
    00051 /// Standard function to receive Palm OS wake up notification.
    00052 ///
    00053 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00054 /// @return Library error code.
    00055 Err TonesLibWake (UInt16 refNum)
    00056                  SYS_TRAP (sysLibTrapWake);
    00057
    00058 /// Standard function to receive Palm OS sleep notification.
    00059 ///
    00060 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00061 /// @return Library error code.
    00062 Err TonesLibSleep (UInt16 refNum)
    00063                  SYS_TRAP (sysLibTrapSleep);
    00064
    00065 /// Get the list of tone names.
    00066 ///
    00067 /// @param refNum:      IN:  Library reference number from SysLibLoad.
    00068 /// @param list:        IN:  Pointer to the list of tone names to return.
    00069 /// @param listLength:  OUT: Count of how many tone names are in the list.
    00070 /// @return Library error code.
    00071 Err TonesLibGetToneList (UInt16 refNum, ToneItemPtr * list, UInt16 * listLength)
    00072                  SYS_TRAP (tonesLibTrapGetToneList);
    00073
    00074 /// Get the list of tone IDs.
    00075 ///
    00076 /// @param refNum:      IN:  Library reference number from SysLibLoad.
    00077 /// @param list:        IN:  Pointer to the list of tone IDs to return.
    00078 /// @param listLength:  OUT: Count of how many tone IDs are in the list.
    00079 /// @return Library error code.
    00080 Err TonesLibGetToneIDs ( UInt16 refNum, ToneIdentifier ** list, UInt16 * listLength)
    00081                  SYS_TRAP (tonesLibTrapGetToneIDs);
    00082
    00083 /// Get the name of a certain tone given its ID.
    00084 ///
    00085 /// @param refNum:      IN:  Library reference number from SysLibLoad.
    00086 /// @param toneId:      IN:  Tone ID of the tone name to get.
    00087 /// @param name:        I/O: Pointer to the returned tone name.
    00088 /// @param maxLength:   IN:  Size of the name buffer in bytes.
    00089 /// @return Library error code.
    00090 Err TonesLibGetToneName (UInt16 refNum, ToneIdentifier toneId, CharPtr name, UInt16
    00091     maxLength)
    00092                  SYS_TRAP (tonesLibTrapGetToneName);
    00093
    00094 /// Get the tone data size given its ID.
    00095 ///
    00096 /// @param refNum:      IN:  Library reference number from SysLibLoad.
    00097 /// @param toneId:      IN:  ID number of the tone.
    00098 /// @param sizeP:       OUT: Size of the specified tone.
    00099 /// @return Library error code.
    00100 Err TonesLibGetToneSize (UInt16 refNum, ToneIdentifier toneId, UInt32* sizeP)
    00101                  SYS_TRAP (tonesLibTrapGetToneSize);
    00102
    00103 /// Play a tone given its ID.
    00104 ///
    00105 /// @param refNum:      IN: Library reference number from SysLibLoad.
    00106 /// @param toneId:      IN: ID of the tone to play.
    00107 /// @param playCount:   IN: Number of times you want the tone repeated.
    00108 /// @param volume:      IN: Volume level at which you want the tone played.
    00109 /// @param vibrate:     IN: Vibrate mode to use when playing the tone.
    00110 /// @param blocking:    IN: Controls whether the tone play is a blocking call
    00111 ///                         or play in the background and return immediately.
    00112 /// @return Library error code.
    00113 Err TonesLibPlayTone (UInt16 refNum, ToneIdentifier toneId, UInt16 playCount,
    00114     ToneVolume volume, ToneVibrateType vibrate, Boolean blocking)
    00115                  SYS_TRAP (tonesLibTrapPlayTone);
    00116
    00117 /// Add a MIDI tone to the system tone database.
    00118 ///
    00119 /// @param refNum:          IN: Library reference number from SysLibLoad.
    00120 /// @param midiTone:        IN: The data buffer handle where the midi tone data is located.
    00121 /// @param toneName:        IN: Name of the tone.
    00122 /// @param protectedTone:   IN: Save tone as protected record in the tone database.
    00123 /// @return Library error code.
    00124 Err TonesLibAddMidiTone (UInt16 refNum, MemHandle midiTone, CharPtr toneName,
    00125     Boolean protectedTone)
    00126                  SYS_TRAP (tonesLibTrapAddMidiTone);
    00127
    00128 /// Create new tone and return the pointer to the start of the sound stream.
    00129 ///
    00130 /// @param refNum:          IN:  Library reference number from SysLibLoad.
    00131 /// @param streamP:         OUT: Pointer to the sound stream of the new tone.
    00132 /// @param toneType:        IN:  Type of the tone. @see ToneType.
    00133 /// @param toneName:        IN:  Name of the tone.
    00134 /// @param protectedTone:   IN:  Save tone as protected record in the tone database.
    00135 /// @return Library error code.
    00136 Err TonesLibToneCreate (UInt16 refNum, UInt32* streamP, ToneType toneType,
    00137                         CharPtr toneName, Boolean protectedTone)
    00138                  SYS_TRAP (tonesLibTrapToneCreate);
    00139
    00140 /// Write sound data to the stream returned by TonesLibToneCreate().
    00141 ///
    00142 /// @param refNum:   IN: Library reference number from SysLibLoad.
    00143 /// @param stream:   IN: Reference to the steam returned by TonesLibToneCreate().
    00144 /// @param dataP:    IN: Pointer to the Tone(Sound) data.
    00145 /// @param size:     IN: Size of the data to be written.
    00146 /// @return Library error code.
    00147 Err TonesLibToneWrite (UInt16 refNum, UInt32 stream, const void* dataP, Int32 size)
    00148                  SYS_TRAP (tonesLibTrapToneWrite);
    00149
    00150 /// Close the reference to the tone stream.
    00151 ///
    00152 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00153 /// @param stream: IN:  Reference to the steam returned by TonesLibToneCreate().
    00154 /// @return Library error code.
    00155 Err TonesLibToneClose (UInt16 refNum, UInt32 stream)
    00156                  SYS_TRAP (tonesLibTrapToneClose);
    00157
    00158 /// Display UI to manage tones. Users can delete, play, or send a tone from this UI.
    00159 ///
    00160 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00161 /// @return Library error code.
    00162 Err TonesLibManageTones (UInt16 refNum)
    00163                  SYS_TRAP (tonesLibTrapManageTones);
    00164
    00165 /// Delete a tone given its ID.
    00166 ///
    00167 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00168 /// @param toneId: IN:  ID of the tone to be deleted.
    00169 /// @return Library error code.
    00170 Err TonesLibDeleteTone (UInt16 refNum, ToneIdentifier toneId)
    00171                   SYS_TRAP (tonesLibTrapDeleteTone);
    00172
    00173 /// Create the default tone database if it does not exist, and verify that all the tones
    00174 /// in a database are resident on the device.
    00175 ///
    00176 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00177 /// @return Library error code.
    00178 Err TonesLibInitTonesDB (UInt16 refNum)
    00179                    SYS_TRAP (tonesLibTrapInitTonesDB);
    00180
    00181 /// Get the sound preference for a type of (application) sound.
    00182 ///
    00183 /// @param refNum:       IN:    Library reference number from SysLibLoad.
    00184 /// @param soundType:    IN:    Type of (application: email, SMS, phone call, etc) sound.
    00185 /// @param soundPrefs:   OUT:   Preference settings for a type of sound.
    00186 /// @return Library error code.
    00187 Err TonesLibGetSoundPrefs (UInt16 refNum, SoundPrefType soundType, SoundPreference * soundPrefs)
    00188                   SYS_TRAP (tonesLibTrapGetSoundPrefs);
    00189
    00190 /// Set the sound preference for a type of (application) sound.
    00191 ///
    00192 /// @param refNum:       IN:    Library reference number from SysLibLoad.
    00193 /// @param soundType:    IN:    Type of (application) sound.
    00194 /// @param soundPrefs:   IN:    Preference settings for the type of sound.
    00195 /// @return Library error code.
    00196 Err TonesLibSetSoundPrefs (UInt16 refNum, SoundPrefType soundType, SoundPreference * soundPrefs)
    00197                   SYS_TRAP (tonesLibTrapSetSoundPrefs);
    00198
    00199 /// Display the UI to select tones and return the tone type, tone name, and handle to
    00200 /// the tone data.
    00201 ///
    00202 /// @param refNum:      IN:  Library reference number from SysLibLoad.
    00203 /// @param toneType:    OUT: Type of tone.
    00204 /// @param toneH:       OUT: Handle to the tone selected. Must be freed by the caller.
    00205 /// @param name:        OUT: Name of the tone.
    00206 /// @return Library error code.
    00207 Err TonesLibPickTone (UInt16 refNum, ToneType * toneType, MemHandle *toneH, Char
    00208     * name)
    00209                   SYS_TRAP (tonesLibTrapPickTone);
    00210
    00211 /// Stop the playback of the current tone.
    00212 ///
    00213 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00214 /// @return Library error code.
    00215 Err TonesLibStopTone (UInt16 refNum)
    00216                   SYS_TRAP (tonesLibTrapStopTone);
    00217
    00218 /// Get the sound-on volume of a sound type.
    00219 ///
    00220 /// @param refNum:          IN:  Library reference number from SysLibLoad.
    00221 /// @param soundType:       IN:  Type of (application) sound.
    00222 /// @param soundOnVolumeP:  OUT: Volume of the sound.
    00223 /// @return Library error code.
    00224 Err TonesLibGetSoundOnVolume (UInt16 refNum, SoundPrefType soundType,
    00225                               ToneVolume* soundOnVolumeP)
    00226                   SYS_TRAP (tonesLibTrapGetSoundOnVolume);
    00227
    00228 /// Set the sound-on volume of a sound type.
    00229 ///
    00230 /// @param refNum:          IN: Library reference number from SysLibLoad.
    00231 /// @param soundType:       IN: Type of (application) sound.
    00232 /// @param soundOnVolume:   IN: Volume of the tone.
    00233 /// @return Library error code.
    00234 Err TonesLibSetSoundOnVolume (UInt16 refNum, SoundPrefType soundType,
    00235                               ToneVolume soundOnVolume)
    00236                   SYS_TRAP (tonesLibTrapSetSoundOnVolume);
    00237
    00238 /// Display the UI to create and/or manages tones.
    00239 ///
    00240 /// @param refNum:  IN: Library reference number from SysLibLoad.
    00241 /// @param flags:   IN: Set to kTonesDialogFlagNonModal to hide the Done button from the dialog.
    00242 /// @return Library error code.
    00243 Err TonesLibDoDialog (UInt16 refNum, UInt32 flags)
    00244                  SYS_TRAP (tonesLibTrapDoDialog);
    00245
    00246 /// No definition.
    00247 ///
    00248 /// @param refNum: IN:  Library reference number from SysLibLoad.
    00249 /// @return Library error code.
    00250 Err TonesLibRecordTone (UInt16 refNum)
    00251                 SYS_TRAP (tonesLibTrapToneRecord);
    00252
    00253 /// Query or toggle whether ring tones are escalated in volume when played.
    00254 ///
    00255 /// @param refNum:  IN: Library reference number from SysLibLoad.
    00256 /// @param set:     IN: true if setting, false if querying.
    00257 /// @param value:   IN: Value to set if setting, queried value if querying.
    00258 /// @return Library error code.
    00259 Err TonesLibEscalateRingTones (UInt16 refNum, Boolean set, Boolean *value)
    00260                  SYS_TRAP (tonesLibTrapEscalateRingTones);
    00261
    00262 /// Play a ring tone given its ID.  The difference between this and PlayTone is
    00263 /// that tones played this way are affected by TonesLibEscalateRingTones().
    00264 ///
    00265 /// @param refNum:      IN: Library reference number from SysLibLoad.
    00266 /// @param toneId:      IN: ID of the tone to play.
    00267 /// @param playCount:   IN: Number of times you want the tone repeated.
    00268 /// @param volume:      IN: Volume level at which you want the tone played.
    00269 /// @param vibrate:     IN: Vibrate mode to use when playing the tone.
    00270 /// @param blocking:    IN: Controls whether the tone play is a blocking call
    00271 ///                         or play in the background and return immediately.
    00272 /// @return Library error code.
    00273 Err TonesLibPlayRingTone (UInt16 refNum, ToneIdentifier toneId, UInt16 playCount,
    00274     ToneVolume volume, ToneVibrateType vibrate, Boolean blocking)
    00275                  SYS_TRAP (tonesLibTrapPlayRingTone);
    00276
    00277 // Save a copy of undeletable tones into a separate hidden db
    00278 // so that we can copy them back to main MIDI db. This is in case that delete
    00279 // protected tones got lost during recovery hot sync where MIDI db from the
    00280 // computer profile was copied over to the device.
    00281 // Called from SoundPhone Panel at SyncStart notification
    00282 //
    00283 // @param   refNum  IN: Library reference number from SysLibLoad.
    00284 // @return  Library error code
    00285 Err TonesLibSaveUndeletableTones(UInt16 refNum)
    00286                  SYS_TRAP (tonesLibTrapSaveUndeletableTones);
    00287
    00288 // After hot Sync has finished copy back delete protected tones from
    00289 // backup db to main MIDI db. See TonesLibSaveUndeletableTones also.
    00290 // Called from SoundPhone Panel at SyncFinish notification
    00291 //
    00292 // @param   refNum  IN: Library reference number from SysLibLoad.
    00293 // @return  Library error code
    00294 Err TonesLibCopyBackUndeletableTones(UInt16 refNum)
    00295                  SYS_TRAP (tonesLibTrapCopyBackUndeletableTones);
    00296
    00297 #ifdef __cplusplus
    00298 }
    00299 #endif
    00300
    00301 #endif // __TONESLIB__H__

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