Header Files » Incs » 68k » libraries » toneslibrary

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