API Guide Home (Online version only) |

# HsSoundLib.h File Reference

## Detailed Description

Public 68K include file for main sound support for Treo 600 and Treo 650 smartphones.

This header file and associated header files support the specific sound functionality of the Treo smartphones. You should use the Palm OS Sound Manager APIs for most of your work.

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 HsSoundLib.h.

Include dependency graph for HsSoundLib.h:

Go to the source code of this file.

## Defines

Preference Macros

- #define PmSndSetPreference(libRef, prefID, prefValue) HsSndSwitchSetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID) (prefValue), (HsSndPortClass) (prefID) );
- #define PmSndGetPreference(libRef, prefID, prefValuePtr) HsSndSwitchGetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID *) (prefValuePtr), (HsSndPortClass) (prefID) );

Special Function Macros

- #define PmSndStreamSetAttackEnvID(libRef, stream, attackEnvID) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetAttackEnvID, (HsSndCmdType) attackEnvID, (void*)0, (UInt32) stream )
- #define PmSndStreamPause(libRef, stream) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatPauseStream, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )
- #define PmSndStreamResume(libRef, stream) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatResumeStream, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )
- #define PmSndStreamStoppable(libRef, stream) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetStoppable, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )

## Functions

- Err HsSndOpen (UInt16 libRef)
- Err HsSndClose (UInt16 libRef)
- UInt32 HsSndGetVersion (UInt16 libRef)
- Err HsSndPortGetInfo (UInt16 libRef, HsSndPortID portID, HsSndPortInfo *portInfoP)
- Err HsSndPortSetParam (UInt16 libRef, HsSndPortID portID, HsSndParam paramSel, Int16 value, Int16 *returnValue)
- Err HsSndSwitchGetPort (UInt16 libRef, HsSndSwitchID switchID, HsSndPortID *portIDP, HsSndPortClass portClass)
- Err HsSndSwitchSetPort (UInt16 libRef, HsSndSwitchID switchID, HsSndPortID portID, HsSndPortClass portClass)
- Err HsSndTonePlay (UInt16 libRef, UInt32 freq, UInt16 amp, UInt32 duration, UInt32 toneType)
- Err HsSndToneStop (UInt16 libRef)
- Err HsSndFormatPlay (UInt16 libRef, HsSndFormatType format, HsSndCmdType command, void *commandData, UInt32 commandFlags)
- Err HsSndFormatRecord (UInt16 libRef, HsSndFormatType format, HsSndCmdType command, void *commandData, UInt32 commandFlags)
- Err HsSndGetUserVolume (UInt16 libRef, HsSndMode mode, Int16 *volumeP)
- Err HsSndSetUserVolume (UInt16 libRef, HsSndMode mode, Int16 volume)
- Err PmSndClkGetTicksPerSecond (UInt16 libRef, PmClkTickRef clkRef, UInt32 *ticksPerSecondP)
- Err PmSndClkGetTickCount (UInt16 libRef, PmClkTickRef clkRef, PmSndU64 *clockTicksP)
- Err PmSndGetPosition (UInt16 libRef, SndStreamRef streamRef, PmSndU64 *sampleNumberP, PmClkTickRef clkRef, PmSndU64 *clockTicksP)

## Define Documentation

#define PmSndGetPreference | ( | libRef,
|  | prefID,
|  | prefValuePtr |  | ) | HsSndSwitchGetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID *) (prefValuePtr), (HsSndPortClass) (prefID) );

Definition at line 52 of file HsSoundLib.h.

#define PmSndSetPreference | ( | libRef,
|  | prefID,
|  | prefValue |  | ) | HsSndSwitchSetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID) (prefValue), (HsSndPortClass) (prefID) );

Definition at line 49 of file HsSoundLib.h.

#define PmSndStreamPause | ( | libRef,
|  | stream |  | ) | HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatPauseStream, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )

Definition at line 62 of file HsSoundLib.h.

#define PmSndStreamResume | ( | libRef,
|  | stream |  | ) | HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatResumeStream, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )

Definition at line 63 of file HsSoundLib.h.

#define PmSndStreamSetAttackEnvID | ( | libRef,
|  | stream,
|  | attackEnvID |  | ) | HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetAttackEnvID, (HsSndCmdType) attackEnvID, (void*)0, (UInt32) stream )

Definition at line 61 of file HsSoundLib.h.

#define PmSndStreamStoppable | ( | libRef,
|  | stream |  | ) | HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetStoppable, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )

Definition at line 64 of file HsSoundLib.h.

## Function Documentation

Err HsSndClose | ( | UInt16 | libRef | ) |

Close the Sound library instance.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)

Returns:
  Library error code.

Err HsSndFormatPlay | ( | UInt16 | libRef,
|  | HsSndFormatType | format,
|  | HsSndCmdType | command,
|  | void * | commandData,
|  | UInt32 | commandFlags |
| ) |  |  |

Play formatted audio data, such as MIDI, AMR, and so forth.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | format,: | IN: Audio format to be played.
  | command,: | IN: Command to execute. Should be set to hsSndCmdPlay.
  | commandData,: | IN: Command to the sound buffer structure HsSndBufferData
  | commandFlags,: | IN: Command flags for the play command.

Returns:
  Library error code.

Err HsSndFormatRecord | ( | UInt16 | libRef,
|  | HsSndFormatType | format,
|  | HsSndCmdType | command,
|  | void * | commandData,
|  | UInt32 | commandFlags |
| ) |  |  |

Records formatted audio data, such as MIDI, AMR, and so forth. (Currently a stub and not implemented yet).

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | format,: | IN: Audio format to be recorded.
  | command,: | IN: Command to execute. Should be set to hsSndCmdPlay.
  | commandData,: | IN: Pointer to the sound buffer structure HsSndBufferData.
  | commandFlags,: | IN: The command flags for the record command.

Returns:
  Library error code.

Err HsSndGetUserVolume | ( | UInt16 | libRef,
|  | HsSndMode | mode,
|  | Int16 * | volumeP |
| ) |  |  |

Get the user volume setting for the specified sound mode.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | mode,: | IN: The audio configuration mode.
  | volumeP,: | IN: The sound level.

Returns:
  Library error code.

UInt32 HsSndGetVersion | ( | UInt16 | libRef | ) |

Returns the library version number.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)

Returns:
  Library error code.

Err HsSndOpen | ( | UInt16 | libRef | ) |

Open and initialize the Sound library instance.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)

Returns:
  Library error code.

Err HsSndPortGetInfo | ( | UInt16 | libRef,
|  | HsSndPortID | portID,
|  | HsSndPortInfo * | portInfoP |
| ) |  |  |

Returns information about the sound port.

Parameters:

  | libRef,: | IN: Library reference number
  | portID,: | IN: Sound port ID.
  | *portInfoP,: | IN: Pointer to an HsSndPortInfo structure provided by the caller.

Returns:
  Library error code.

Err HsSndPortSetParam | ( | UInt16 | libRef,
|  | HsSndPortID | portID,
|  | HsSndParam | paramSel,
|  | Int16 | value,
|  | Int16 * | returnValue |
| ) |  |  |

Set a sound port's audio parameter.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)
  | portID,: | IN: Sound port ID.
  | paramSel,: | IN: Parameter selector.
  | value,: | IN: Value to set.
  | returnValue,: | OUT: Pointer to the updated value.

Returns:
  Library error code.

Err HsSndSetUserVolume | ( | UInt16 | libRef,
|  | HsSndMode | mode,
|  | Int16 | volume |
| ) |  |  |

Set the user volume for the specified sound mode.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | mode,: | IN: The audio configuration mode.
  | volume,: | IN: The sound level.

Returns:
  Library error code.

Err HsSndSwitchGetPort | ( | UInt16 | libRef,
|  | HsSndSwitchID | switchID,
|  | HsSndPortID * | portIDP,
|  | HsSndPortClass | portClass |
| ) |  |  |

Get the current sound port for a particular switch.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)
  | switchID,: | IN: Switch ID.
  | portIDP,: | OUT: Port ID returned to the caller.
  | portClass,: | IN: Port class selector.

Returns:
  Library error code.

Err HsSndSwitchSetPort | ( | UInt16 | libRef,
|  | HsSndSwitchID | switchID,
|  | HsSndPortID | portID,
|  | HsSndPortClass | portClass |
| ) |  |  |

Set the current sound port for a particular switch.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad)
  | switchID,: | IN: Switch ID.
  | portID,: | IN: The new port ID for the audio switch.
  | portClass,: | IN: Port class selector.

Returns:
  Library error code.

Err HsSndTonePlay | ( | UInt16 | libRef,
|  | UInt32 | freq,
|  | UInt16 | amp,
|  | UInt32 | duration,
|  | UInt32 | toneType |
| ) |  |  |

Play a sound.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | freq,: | IN: Frequency of the tone.
  | amp,: | IN: Amplitude of the tone.
  | duration,: | IN: Duration of the tone.
  | toneType,: | IN: Type of tone to play.

Returns:
  Library error code.

Err HsSndToneStop | ( | UInt16 | libRef | ) |

Stop playing a sound that was started with HsSndTonePlay().

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).

Returns:
  Library error code.

Err PmSndClkGetTickCount | ( | UInt16 | libRef,
|  | PmClkTickRef | clkRef,
|  | PmSndU64 * | clockTicksP |
| ) |  |  |

Get current clock tick count.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | clkRef,: | IN: Clock reference number (see HsSoundLibCommon.h).
  | clockTicksP | OUT: Returns the current clock tick count.

Returns:
  Library error code.

Err PmSndClkGetTicksPerSecond | ( | UInt16 | libRef,
|  | PmClkTickRef | clkRef,
|  | UInt32 * | ticksPerSecondP |
| ) |  |  |

Get the number of clock ticks per second

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | clkRef,: | IN: Clock reference number (see HsSoundLibCommon.h).
  | ticksPerSecondP | OUT: Returns the tick per second

Returns:
  Library error code.

Err PmSndGetPosition | ( | UInt16 | libRef,
|  | SndStreamRef | streamRef,
|  | PmSndU64 * | sampleNumberP,
|  | PmClkTickRef | clkRef,
|  | PmSndU64 * | clockTicksP |
| ) |  |  |

Get current stream sample position and current clock tick count.

Parameters:

  | libRef,: | IN: Library reference number (from SysLibLoad).
  | streamRef | IN: Sound stream channel reference id.
  | sampleNumberP,: | OUT: Returns the current sample number for the stream.
  | clkRef,: | IN: Clock reference number (see HsSoundLibCommon.h).
  | clockTicksP | OUT: Returns the current clock tick count.

Returns:
  Library error code.

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