API Guide Home (Online version only) |

# TonesLib.h File Reference

## Detailed Description

Public 68K include file that controls the MIDI tones on a device.

Notes:

The calling application should always load this library with SysLibLoad() before use, even if it is already open by another application(ie, SysLibFind() returns a valid refnum). When the application is done with the library, it should be unloaded with SysLibRemove(). We do this because there is no good way to synchronize loading and unloading of libraries among multiple applications. It also greatly simplifies internal synchronization.

Definition in file TonesLib.h.

Go to the source code of this file.

## Defines

- #define kTonesLibVersionEscalation 10

## Functions

- Err TonesLibOpen (UInt16 refNum)
- Err TonesLibClose (UInt16 refNum)
- Err TonesLibWake (UInt16 refNum)
- Err TonesLibSleep (UInt16 refNum)
- Err TonesLibGetToneList (UInt16 refNum, ToneItemPtr *list, UInt16 *listLength)
- Err TonesLibGetToneIDs (UInt16 refNum, ToneIdentifier **list, UInt16 *listLength)
- Err TonesLibGetToneName (UInt16 refNum, ToneIdentifier toneId, CharPtr name, UInt16 maxLength)
- Err TonesLibGetToneSize (UInt16 refNum, ToneIdentifier toneId, UInt32 *sizeP)
- Err TonesLibPlayTone (UInt16 refNum, ToneIdentifier toneId, UInt16 playCount, ToneVolume volume, ToneVibrateType vibrate, Boolean blocking)
- Err TonesLibAddMidiTone (UInt16 refNum, MemHandle midiTone, CharPtr toneName, Boolean protectedTone)
- Err TonesLibToneCreate (UInt16 refNum, UInt32 *streamP, ToneType toneType, CharPtr toneName, Boolean protectedTone)
- Err TonesLibToneWrite (UInt16 refNum, UInt32 stream, const void *dataP, Int32 size)
- Err TonesLibToneClose (UInt16 refNum, UInt32 stream)
- Err TonesLibManageTones (UInt16 refNum)
- Err TonesLibDeleteTone (UInt16 refNum, ToneIdentifier toneId)
- Err TonesLibInitTonesDB (UInt16 refNum)
- Err TonesLibGetSoundPrefs (UInt16 refNum, SoundPrefType soundType, SoundPreference *soundPrefs)
- Err TonesLibSetSoundPrefs (UInt16 refNum, SoundPrefType soundType, SoundPreference *soundPrefs)
- Err TonesLibPickTone (UInt16 refNum, ToneType *toneType, MemHandle *toneH, Char *name)
- Err TonesLibStopTone (UInt16 refNum)
- Err TonesLibGetSoundOnVolume (UInt16 refNum, SoundPrefType soundType, ToneVolume *soundOnVolumeP)
- Err TonesLibSetSoundOnVolume (UInt16 refNum, SoundPrefType soundType, ToneVolume soundOnVolume)
- Err TonesLibDoDialog (UInt16 refNum, UInt32 flags)
- Err TonesLibRecordTone (UInt16 refNum)
- Err TonesLibEscalateRingTones (UInt16 refNum, Boolean set, Boolean *value)
- Err TonesLibPlayRingTone (UInt16 refNum, ToneIdentifier toneId, UInt16 playCount, ToneVolume volume, ToneVibrateType vibrate, Boolean blocking)
- Err TonesLibSaveUndeletableTones (UInt16 refNum)
- Err TonesLibCopyBackUndeletableTones (UInt16 refNum)

## Define Documentation

#define kTonesLibVersionEscalation 10

Minimum db version of TonesLibrary database that implements escalation Done this way since we have no GetLibVersion() API.

Definition at line 35 of file TonesLib.h.

## Function Documentation

Err TonesLibAddMidiTone | ( | UInt16 | refNum,
|  | MemHandle | midiTone,
|  | CharPtr | toneName,
|  | Boolean | protectedTone |
| ) |  |  |

Add a MIDI tone to the system tone database.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | midiTone,: | IN: The data buffer handle where the midi tone data is located.
  | toneName,: | IN: Name of the tone.
  | protectedTone,: | IN: Save tone as protected record in the tone database.

Returns:
  Library error code.

Err TonesLibClose | ( | UInt16 | refNum | ) |

Close the Tones library instance.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibCopyBackUndeletableTones | ( | UInt16 | refNum | ) |

Err TonesLibDeleteTone | ( | UInt16 | refNum,
|  | ToneIdentifier | toneId |
| ) |  |  |

Delete a tone given its ID.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneId,: | IN: ID of the tone to be deleted.

Returns:
  Library error code.

Err TonesLibDoDialog | ( | UInt16 | refNum,
|  | UInt32 | flags |
| ) |  |  |

Display the UI to create and/or manages tones.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | flags,: | IN: Set to kTonesDialogFlagNonModal to hide the Done button from the dialog.

Returns:
  Library error code.

Err TonesLibEscalateRingTones | ( | UInt16 | refNum,
|  | Boolean | set,
|  | Boolean * | value |
| ) |  |  |

Query or toggle whether ring tones are escalated in volume when played.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | set,: | IN: true if setting, false if querying.
  | value,: | IN: Value to set if setting, queried value if querying.

Returns:
  Library error code.

Err TonesLibGetSoundOnVolume | ( | UInt16 | refNum,
|  | SoundPrefType | soundType,
|  | ToneVolume * | soundOnVolumeP |
| ) |  |  |

Get the sound-on volume of a sound type.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | soundType,: | IN: Type of (application) sound.
  | soundOnVolumeP,: | OUT: Volume of the sound.

Returns:
  Library error code.

Err TonesLibGetSoundPrefs | ( | UInt16 | refNum,
|  | SoundPrefType | soundType,
|  | SoundPreference * | soundPrefs |
| ) |  |  |

Get the sound preference for a type of (application) sound.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | soundType,: | IN: Type of (application: email, SMS, phone call, etc) sound.
  | soundPrefs,: | OUT: Preference settings for a type of sound.

Returns:
  Library error code.

Err TonesLibGetToneIDs | ( | UInt16 | refNum,
|  | ToneIdentifier ** | list,
|  | UInt16 * | listLength |
| ) |  |  |

Get the list of tone IDs.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | list,: | IN: Pointer to the list of tone IDs to return.
  | listLength,: | OUT: Count of how many tone IDs are in the list.

Returns:
  Library error code.

Err TonesLibGetToneList | ( | UInt16 | refNum,
|  | ToneItemPtr * | list,
|  | UInt16 * | listLength |
| ) |  |  |

Get the list of tone names.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | list,: | IN: Pointer to the list of tone names to return.
  | listLength,: | OUT: Count of how many tone names are in the list.

Returns:
  Library error code.

Err TonesLibGetToneName | ( | UInt16 | refNum,
|  | ToneIdentifier | toneId,
|  | CharPtr | name,
|  | UInt16 | maxLength |
| ) |  |  |

Get the name of a certain tone given its ID.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneId,: | IN: Tone ID of the tone name to get.
  | name,: | I/O: Pointer to the returned tone name.
  | maxLength,: | IN: Size of the name buffer in bytes.

Returns:
  Library error code.

Err TonesLibGetToneSize | ( | UInt16 | refNum,
|  | ToneIdentifier | toneId,
|  | UInt32 * | sizeP |
| ) |  |  |

Get the tone data size given its ID.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneId,: | IN: ID number of the tone.
  | sizeP,: | OUT: Size of the specified tone.

Returns:
  Library error code.

Err TonesLibInitTonesDB | ( | UInt16 | refNum | ) |

Create the default tone database if it does not exist, and verify that all the tones in a database are resident on the device.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibManageTones | ( | UInt16 | refNum | ) |

Display UI to manage tones. Users can delete, play, or send a tone from this UI.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibOpen | ( | UInt16 | refNum | ) |

Open and initialize the Tones library instance.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibPickTone | ( | UInt16 | refNum,
|  | ToneType * | toneType,
|  | MemHandle * | toneH,
|  | Char * | name |
| ) |  |  |

Display the UI to select tones and return the tone type, tone name, and handle to the tone data.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneType,: | OUT: Type of tone.
  | toneH,: | OUT: Handle to the tone selected. Must be freed by the caller.
  | name,: | OUT: Name of the tone.

Returns:
  Library error code.

Err TonesLibPlayRingTone | ( | UInt16 | refNum,
|  | ToneIdentifier | toneId,
|  | UInt16 | playCount,
|  | ToneVolume | volume,
|  | ToneVibrateType | vibrate,
|  | Boolean | blocking |
| ) |  |  |

Play a ring tone given its ID. The difference between this and PlayTone is that tones played this way are affected by TonesLibEscalateRingTones().

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneId,: | IN: ID of the tone to play.
  | playCount,: | IN: Number of times you want the tone repeated.
  | volume,: | IN: Volume level at which you want the tone played.
  | vibrate,: | IN: Vibrate mode to use when playing the tone.
  | blocking,: | IN: Controls whether the tone play is a blocking call or play in the background and return immediately.

Returns:
  Library error code.

Err TonesLibPlayTone | ( | UInt16 | refNum,
|  | ToneIdentifier | toneId,
|  | UInt16 | playCount,
|  | ToneVolume | volume,
|  | ToneVibrateType | vibrate,
|  | Boolean | blocking |
| ) |  |  |

Play a tone given its ID.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | toneId,: | IN: ID of the tone to play.
  | playCount,: | IN: Number of times you want the tone repeated.
  | volume,: | IN: Volume level at which you want the tone played.
  | vibrate,: | IN: Vibrate mode to use when playing the tone.
  | blocking,: | IN: Controls whether the tone play is a blocking call or play in the background and return immediately.

Returns:
  Library error code.

Err TonesLibRecordTone | ( | UInt16 | refNum | ) |

No definition.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibSaveUndeletableTones | ( | UInt16 | refNum | ) |

Err TonesLibSetSoundOnVolume | ( | UInt16 | refNum,
|  | SoundPrefType | soundType,
|  | ToneVolume | soundOnVolume |
| ) |  |  |

Set the sound-on volume of a sound type.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | soundType,: | IN: Type of (application) sound.
  | soundOnVolume,: | IN: Volume of the tone.

Returns:
  Library error code.

Err TonesLibSetSoundPrefs | ( | UInt16 | refNum,
|  | SoundPrefType | soundType,
|  | SoundPreference * | soundPrefs |
| ) |  |  |

Set the sound preference for a type of (application) sound.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | soundType,: | IN: Type of (application) sound.
  | soundPrefs,: | IN: Preference settings for the type of sound.

Returns:
  Library error code.

Err TonesLibSleep | ( | UInt16 | refNum | ) |

Standard function to receive Palm OS sleep notification.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibStopTone | ( | UInt16 | refNum | ) |

Stop the playback of the current tone.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

Err TonesLibToneClose | ( | UInt16 | refNum,
|  | UInt32 | stream |
| ) |  |  |

Close the reference to the tone stream.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | stream,: | IN: Reference to the steam returned by TonesLibToneCreate().

Returns:
  Library error code.

Err TonesLibToneCreate | ( | UInt16 | refNum,
|  | UInt32 * | streamP,
|  | ToneType | toneType,
|  | CharPtr | toneName,
|  | Boolean | protectedTone |
| ) |  |  |

Create new tone and return the pointer to the start of the sound stream.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | streamP,: | OUT: Pointer to the sound stream of the new tone.
  | toneType,: | IN: Type of the tone.

See also:
  ToneType.

Parameters:

  | toneName,: | IN: Name of the tone.
  | protectedTone,: | IN: Save tone as protected record in the tone database.

Returns:
  Library error code.

Err TonesLibToneWrite | ( | UInt16 | refNum,
|  | UInt32 | stream,
|  | const void * | dataP,
|  | Int32 | size |
| ) |  |  |

Write sound data to the stream returned by TonesLibToneCreate().

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.
  | stream,: | IN: Reference to the steam returned by TonesLibToneCreate().
  | dataP,: | IN: Pointer to the Tone(Sound) data.
  | size,: | IN: Size of the data to be written.

Returns:
  Library error code.

Err TonesLibWake | ( | UInt16 | refNum | ) |

Standard function to receive Palm OS wake up notification.

Parameters:

  | refNum,: | IN: Library reference number from SysLibLoad.

Returns:
  Library error code.

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