API Guide Home (Online version only) |

# HsSoundLib.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 Sound
    00007  *
    00008  */
    00009
    00010 /**
    00011  * @file    HsSoundLib.h
    00012  *
    00013  * @brief   Public 68K include file for main sound support for Treo 600
    00014  *          and Treo 650 smartphones.
    00015  *
    00016  * This header file and associated header files support the specific sound
    00017  * functionality of the Treo smartphones. You should use the Palm OS Sound
    00018  * Manager APIs for most of your work.
    00019  *
    00020  * Notes:
    00021  * The calling application should always load this library with
    00022  * SysLibLoad() before use, even if it is already open by another
    00023  * application(ie, SysLibFind() returns a valid refnum). When
    00024  * the application is done with the library, it should be
    00025  * unloaded with SysLibRemove(). We do this because there is
    00026  * no good way to synchronize loading and unloading of libraries
    00027  * among multiple applications. It also greatly simplifies internal
    00028  * synchronization.
    00029  */
    00030
    00031 #ifndef __HSSOUNDLIB__H__
    00032 #define __HSSOUNDLIB__H__
    00033
    00034 /***********************************************************************
    00035  * Palm OS common definitions
    00036  ***********************************************************************/
    00037 #include <PalmOS.h>
    00038 #include <HsSoundLibCommon.h>
    00039
    00040
    00041 #ifdef __cplusplus
    00042 extern "C" {
    00043 #endif
    00044
    00045 /**
    00046  * @name Preference Macros
    00047  */
    00048 /*@{*/
    00049 #define PmSndSetPreference( libRef, prefID, prefValue ) \
    00050         HsSndSwitchSetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID) (prefValue), (HsSndPortClass) (prefID) );
    00051
    00052 #define PmSndGetPreference( libRef, prefID, prefValuePtr ) \
    00053         HsSndSwitchGetPort( libRef, pmSndSwitchID_Preferences, (HsSndPortID *) (prefValuePtr), (HsSndPortClass) (prefID) );
    00054 /*@}*/
    00055
    00056
    00057 /**
    00058  * @name Special Function Macros
    00059  */
    00060 /*@{*/
    00061 #define PmSndStreamSetAttackEnvID(libRef,stream,attackEnvID) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetAttackEnvID, (HsSndCmdType) attackEnvID, (void*)0, (UInt32) stream )
    00062 #define PmSndStreamPause(libRef,stream)  HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatPauseStream,  (HsSndCmdType) 0, (void*) 0, (UInt32) stream )
    00063 #define PmSndStreamResume(libRef,stream) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatResumeStream, (HsSndCmdType) 0, (void*) 0, (UInt32) stream )
    00064 #define PmSndStreamStoppable(libRef,stream) HsSndFormatPlay( libRef, (HsSndFormatType) pmSndFormatSetStoppable,  (HsSndCmdType) 0, (void*) 0, (UInt32) stream )
    00065 /*@}*/
    00066
    00067 /// Open and initialize the Sound library instance.
    00068 ///
    00069 /// @param libRef:  IN: Library reference number (from SysLibLoad)
    00070 /// @return Library error code.
    00071 Err   HsSndOpen (UInt16 libRef)
    00072           SYS_TRAP (kHsSoundLibTrapOpen);
    00073
    00074 /// Close the Sound library instance.
    00075 ///
    00076 /// @param libRef:  IN: Library reference number (from SysLibLoad)
    00077 /// @return Library error code.
    00078 Err   HsSndClose (UInt16 libRef)
    00079           SYS_TRAP (kHsSoundLibTrapClose);
    00080
    00081 /// Returns the library version number.
    00082 ///
    00083 /// @param libRef:  IN: Library reference number (from SysLibLoad)
    00084 /// @return Library error code.
    00085 UInt32  HsSndGetVersion (UInt16 libRef)
    00086           SYS_TRAP (kHsSoundLibTrapGetVersion);
    00087
    00088 /// Returns information about the sound port.
    00089 ///
    00090 /// @param libRef:      IN: Library reference number
    00091 /// @param portID:      IN: Sound port ID.
    00092 /// @param *portInfoP:  IN: Pointer to an HsSndPortInfo structure provided by the caller.
    00093 /// @return Library error code.
    00094 Err   HsSndPortGetInfo (UInt16 libRef, HsSndPortID portID, HsSndPortInfo *portInfoP)
    00095           SYS_TRAP (kHsSoundLibTrapPortGetInfo);
    00096
    00097 /// Set a sound port's audio parameter.
    00098 ///
    00099 /// @param libRef:      IN: Library reference number (from SysLibLoad)
    00100 /// @param portID:      IN: Sound port ID.
    00101 /// @param paramSel:    IN: Parameter selector.
    00102 /// @param value:       IN: Value to set.
    00103 /// @param returnValue: OUT: Pointer to the updated value.
    00104 /// @return Library error code.
    00105 Err   HsSndPortSetParam (UInt16 libRef, HsSndPortID portID, HsSndParam paramSel, Int16 value, Int16 * returnValue)
    00106           SYS_TRAP (kHsSoundLibTrapPortSetParam);
    00107
    00108 /// Get the current sound port for a particular switch.
    00109 ///
    00110 /// @param libRef:      IN: Library reference number (from SysLibLoad)
    00111 /// @param switchID:    IN: Switch ID.
    00112 /// @param portIDP:     OUT: Port ID returned to the caller.
    00113 /// @param portClass:   IN: Port class selector.
    00114 /// @return Library error code.
    00115 Err   HsSndSwitchGetPort (UInt16 libRef, HsSndSwitchID switchID, HsSndPortID * portIDP, HsSndPortClass portClass)
    00116           SYS_TRAP (kHsSoundLibTrapSwitchGetPort);
    00117
    00118 /// Set the current sound port for a particular switch.
    00119 ///
    00120 /// @param libRef:      IN: Library reference number (from SysLibLoad)
    00121 /// @param switchID:    IN: Switch ID.
    00122 /// @param portID:      IN: The new port ID for the audio switch.
    00123 /// @param portClass:   IN: Port class selector.
    00124 /// @return Library error code.
    00125 Err   HsSndSwitchSetPort (UInt16 libRef, HsSndSwitchID switchID, HsSndPortID portID, HsSndPortClass portClass)
    00126           SYS_TRAP (kHsSoundLibTrapSwitchSetPort);
    00127
    00128 /// Play a sound.
    00129 ///
    00130 /// @param libRef:      IN: Library reference number (from SysLibLoad).
    00131 /// @param freq:        IN: Frequency of the tone.
    00132 /// @param amp:         IN: Amplitude of the tone.
    00133 /// @param duration:    IN: Duration of the tone.
    00134 /// @param toneType:    IN: Type of tone to play.
    00135 /// @return Library error code.
    00136 Err   HsSndTonePlay (UInt16 libRef, UInt32 freq, UInt16 amp, UInt32 duration, UInt32 toneType)
    00137           SYS_TRAP (kHsSoundLibTrapTonePlay);
    00138
    00139 /// Stop playing a sound that was started with HsSndTonePlay().
    00140 ///
    00141 /// @param libRef:  IN: Library reference number (from SysLibLoad).
    00142 /// @return Library error code.
    00143 Err   HsSndToneStop (UInt16 libRef)
    00144           SYS_TRAP (kHsSoundLibTrapToneStop);
    00145
    00146 /// Play formatted audio data, such as MIDI, AMR, and so forth.
    00147 ///
    00148 /// @param libRef:          IN: Library reference number (from SysLibLoad).
    00149 /// @param format:          IN: Audio format to be played.
    00150 /// @param command:         IN: Command to execute.  Should be set to hsSndCmdPlay.
    00151 /// @param commandData:     IN: Command to the sound buffer structure HsSndBufferData
    00152 /// @param commandFlags:    IN: Command flags for the play command.
    00153 /// @return Library error code.
    00154 Err   HsSndFormatPlay (UInt16 libRef, HsSndFormatType format, HsSndCmdType command, void * commandData, UInt32 commandFlags)
    00155           SYS_TRAP (kHsSoundLibTrapFormatPlay);
    00156
    00157 /// Records formatted audio data, such as MIDI, AMR, and so forth.
    00158 /// (Currently a stub and not implemented yet).
    00159 ///
    00160 /// @param libRef:          IN: Library reference number (from SysLibLoad).
    00161 /// @param format:          IN: Audio format to be recorded.
    00162 /// @param command:         IN: Command to execute. Should be set to hsSndCmdPlay.
    00163 /// @param commandData:     IN: Pointer to the sound buffer structure HsSndBufferData.
    00164 /// @param commandFlags:    IN: The command flags for the record command.
    00165 /// @return Library error code.
    00166 Err   HsSndFormatRecord (UInt16 libRef, HsSndFormatType format, HsSndCmdType command, void * commandData, UInt32 commandFlags)
    00167           SYS_TRAP (kHsSoundLibTrapFormatRecord);
    00168
    00169 /// Get the user volume setting for the specified sound mode.
    00170 ///
    00171 /// @param libRef:      IN: Library reference number (from SysLibLoad).
    00172 /// @param mode:        IN: The audio configuration mode.
    00173 /// @param volumeP:     IN: The sound level.
    00174 /// @return Library error code.
    00175 Err   HsSndGetUserVolume (UInt16 libRef, HsSndMode mode, Int16 * volumeP)
    00176           SYS_TRAP (kHsSoundLibTrapGetUserVolume);
    00177
    00178 /// Set the user volume for the specified sound mode.
    00179 ///
    00180 /// @param libRef:  IN: Library reference number (from SysLibLoad).
    00181 /// @param mode:    IN: The audio configuration mode.
    00182 /// @param volume:  IN: The sound level.
    00183 /// @return Library error code.
    00184 Err   HsSndSetUserVolume (UInt16 libRef, HsSndMode mode, Int16 volume)
    00185           SYS_TRAP (kHsSoundLibTrapSetUserVolume);
    00186
    00187
    00188 /// Get the number of clock ticks per second
    00189 ///
    00190 /// @param libRef:  IN: Library reference number (from SysLibLoad).
    00191 /// @param clkRef:  IN: Clock reference number (see HsSoundLibCommon.h).
    00192 /// @param ticksPerSecondP  OUT: Returns the tick per second
    00193 /// @return Library error code.
    00194 Err    PmSndClkGetTicksPerSecond ( UInt16 libRef, PmClkTickRef clkRef, UInt32* ticksPerSecondP )
    00195           SYS_TRAP (kPmSoundLibTrapClkGetTicksPerSecond);
    00196
    00197 /// Get current clock tick count.
    00198 ///
    00199 /// @param libRef:  IN: Library reference number (from SysLibLoad).
    00200 /// @param clkRef:  IN: Clock reference number (see HsSoundLibCommon.h).
    00201 /// @param clockTicksP  OUT: Returns the current clock tick count.
    00202 /// @return Library error code.
    00203 Err    PmSndClkGetTickCount ( UInt16 libRef, PmClkTickRef clkRef, PmSndU64* clockTicksP )
    00204           SYS_TRAP (kPmSoundLibTrapClkGetTickCount);
    00205
    00206 /// Get current stream sample position and current clock tick count.
    00207 ///
    00208 /// @param libRef:  IN: Library reference number (from SysLibLoad).
    00209 /// @param streamRef IN: Sound stream channel reference id.
    00210 /// @param sampleNumberP: OUT: Returns the current sample number for the stream.
    00211 /// @param clkRef:  IN: Clock reference number (see HsSoundLibCommon.h).
    00212 /// @param clockTicksP  OUT: Returns the current clock tick count.
    00213 /// @return Library error code.
    00214 Err    PmSndGetPosition ( UInt16 libRef, SndStreamRef streamRef, PmSndU64* sampleNumberP, PmClkTickRef clkRef, PmSndU64* clockTicksP )
    00215           SYS_TRAP (kPmSoundLibTrapGetPosition);
    00216
    00217
    00218 #ifdef __cplusplus
    00219 }
    00220 #endif
    00221
    00222 #endif // __HSSOUNDLIB__H__

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