API Guide Home (Online version only) |

# HsSoundLibCommon.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004-2006 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @defgroup Sound Sound Library
    00007  * @brief       This library provides support for the specific sound functionality
    00008  *              of the Treo smartphones.
    00009  *
    00010  * Developers should be able to use Palm OS Sound Manager APIs for most of the work.
    00011  * The calling application should always load this library with SysLibLoad() before
    00012  * use, even if it is already open by another application (ie. SysLibFind() returns
    00013  * a valid refNum). When the application is done with the library it should be
    00014  * unloaded with SysLibRemove(). We do this because there is no good way to synchronize
    00015  * loading and unloading of libraries among multiple applications. It also greatly
    00016  * simplifies internal synchronization.
    00017  *
    00018  * @{
    00019  * @}
    00020  */
    00021 /**
    00022  * @ingroup Sound
    00023  */
    00024
    00025 /**
    00026  * @file    HsSoundLibCommon.h
    00027  *
    00028  * @brief   Public 68K/Arm common header file for sound support for Treo 600,
    00029  *          Treo 650, and Treo 700p smartphones and later models.
    00030  *
    00031  * This file contains the common constants and structures to be used with
    00032  * the sound library.
    00033  *
    00034  */
    00035
    00036 #ifndef __HSSOUNDLIB_COMMON__H__
    00037 #define __HSSOUNDLIB_COMMON__H__
    00038
    00039 /***********************************************************************
    00040  * Palm OS common definitions
    00041  ***********************************************************************/
    00042
    00043 #include <PalmTypes.h>
    00044 #include <Common/System/HsErrorClasses.h>
    00045
    00046 #if CPU_TYPE == CPU_ARM
    00047     typedef unsigned long long  PmSndU64;
    00048 #elif CPU_TYPE == CPU_x86
    00049     typedef __int64             PmSndU64;
    00050 #else
    00051     typedef unsigned long long  PmSndU64;
    00052 #endif
    00053
    00054 /**
    00055  * @name HsSoundLib information
    00056  *
    00057  */
    00058 /*@{*/
    00059 #define hsSndLibVersion             0x010D0000      /**<Version of the sound library. */
    00060 #define hsSoundLibCreatorID         hsFileSoundLib  /**<Creator ID of the sound library. */
    00061 #define hsSoundLibTypeID            sysFileTLibrary /**<Type of the sound library. */
    00062 #define hsSoundLibName              "HsSoundLib"    /**<Name of the sound library. */
    00063 /*@}*/
    00064
    00065 /**
    00066  * @name Sound library event notifications
    00067  *
    00068  * Note: Each one of these notifications are reserved as Creator IDs with PalmSource
    00069  */
    00070 /*@{*/
    00071 #define hsSndNotify                 hsFileSoundLib /**<HsSoundLib broadcaster's ID */
    00072 #define hsSndNotifyUnplugged        'hOff' /**<No accesory is currently attached to the headset jack. */
    00073 #define hsSndNotifyHeadset          'hSet' /**<Headset jack connected and configured for mono headset with microphone. */
    00074 #define hsSndNotifyHeadphones       'hPho' /**<Headset jack connected and configured for stereo headphones. */
    00075 #define hsSndNotifyHybrid           'hHyb' /**<A hybrid headset/headphone is currently attached to the headset jack. */
    00076 #define hsSndNotifyNotHybrid        'hNoH' /**<Currently attached peripheral on headset jack is Not a hybrid headset (see hsSndNotifyHybrid). */
    00077 #define hsSndNotifyAnswerButton     'hAns' /**<While a headset or hybrid was connected, the answer-button event was detected. */
    00078 #define hsSndNotifyAnswerHold       'hHol' /**<After hsSndNotifyAnswerButton notification, this event is sent if answer-button is still held down for some time. */
    00079 #define hsSndNotifyAnswerRelease    'hRel' /**<After hsSndNotifyAnswerButton notification, this event is sent when answer-button released. */
    00080 #define hsSndNotifyRingerSwitchOn   'hROn' /**<Notifies that ringer switch is in the on (play sounds to back speaker) position. */
    00081 #define hsSndNotifyRingerSwitchOff  'hROf' /**<Notifies that ringer switch is in the silent (no sounds to back speaker) position. */
    00082 #define hsSndNotifyHighPriority     'hHPr' /**<A high priority sound is about to start playing. */
    00083 #define hsSndNotifyAlert            'hAlr' /**<An alert sound is about to start playing. */
    00084 #define hsSndNotifyCarkitActive     'hCar' /**<Wired carkit has been activated, audio goes to carkit path. */
    00085 #define hsSndNotifyCarkitInactive   'hCOf' /**<Wired carkit is no longer active, audio routes normally. */
    00086 #define hsSndNotifyAthenaAudio      'hAta' /**<Automatic audio switches will route to Athena connector from now on (Treo-650 and later). */
    00087 /*@}*/
    00088
    00089 /**
    00090  * @name Sound library resource types
    00091  *
    00092  */
    00093 /*@{*/
    00094 #define hsSndRsrcAudioTableType     'hTbl' /**<Resource contains audio table that can be loaded to audio driver. */
    00095 #define hsSndRsrcAudioTableID       25000  /**<Default audio table ID which can be loaded automatically during reset. */
    00096 /*@}*/
    00097
    00098 /**
    00099  * @name Sound library error codes
    00100  */
    00101 /*@{*/
    00102 #define hsSndErrBase                hsSoundLibErrorClass /* 0x7500 == 29952 */
    00103 #define HS_SND_ERR(x)               ((Err)((x) + hsSndErrBase))
    00104 #define hsSndErr_Failed             (HS_SND_ERR(1))  /**<The operation or request failed. */
    00105 #define hsSndErr_NotSupported       (HS_SND_ERR(2))  /**<Attempt to use functionality that is not supported in this version. */
    00106 #define hsSndErr_InvalidPort        (HS_SND_ERR(3))  /**<An invalid port was passed to a function. Operation failed. */
    00107 #define hsSndErr_PortCannotMute     (HS_SND_ERR(4))  /**<Unable to change mute state on a port that does not have mute capabilities. */
    00108 #define hsSndErr_PortCannotVolume   (HS_SND_ERR(5))  /**<Unable to change volume gains on a port that does not have volume capabilities. */
    00109 #define hsSndErr_PortCannotBoost    (HS_SND_ERR(6))  /**<Unable to change boost state on a port that does not have boost capabilities. */
    00110 #define hsSndErr_PortCannotPan      (HS_SND_ERR(7))  /**<Unable to change pan settings on a port that does not have panning capabilities. */
    00111 #define hsSndErr_InvalidSwitch      (HS_SND_ERR(8))  /**<An invalid switch was passed to a function. Operation failed. */
    00112 #define hsSndErr_UnknownSndParam    (HS_SND_ERR(9))  /**<An unknown HsSndParam selector was passed to a function call. */
    00113 #define hsSndErr_UnknownPortClass   (HS_SND_ERR(10)) /**<An unknown HsSndPortClass value was passed to a function call. */
    00114 #define hsSndErr_PortIDNotInClass   (HS_SND_ERR(11)) /**<The portID/portClass combination is not supported. */
    00115 #define hsSndErr_PortMuteLocked     (HS_SND_ERR(12)) /**<Unable to change mute state when hsSndParamMode_Normal is the default. */
    00116 #define hsSndErr_PortVolumeLocked   (HS_SND_ERR(13)) /**<Unable to change volume parameter when hsSndParamMode_Normal is the default. */
    00117 #define hsSndErr_PortBoostLocked    (HS_SND_ERR(14)) /**<Unable to change boost state when hsSndParamMode_Normal is the default. */
    00118 #define hsSndErr_PortPanLocked      (HS_SND_ERR(15)) /**<Unable to change pan value when hsSndParamMode_Normal is the default. */
    00119 #define hsSndErr_DoMidiProgressMsg  (HS_SND_ERR(16)) /**<Special message returned by Midi progress callback to request a dynamic volume change. */
    00120 #define hsSndErr_UnknownClkRef      (HS_SND_ERR(17)) /**<Unknown clock reference passed to synchronization clock utility */
    00121 #define hsSndErr_InvalidPrefValue   (HS_SND_ERR(18)) /**<Unsupported or invalid audio preference value */
    00122 #define hsSndErr_LastPublicError    (HS_SND_ERR(63)) /**<just a marker for last public library error code, private sound error codes start at 64 */
    00123 /*@}*/
    00124
    00125 /**
    00126  * Beeps
    00127  *
    00128  * Provides additional system sounds for PalmOS SndPlaySystemSound.
    00129  */
    00130 enum hsSndSysBeepTag
    00131 {
    00132     hsSndCardInsert = 64, /**<No definition. */
    00133     hsSndCardRemove, /**<No definition. */
    00134     hsSndSyncStart, /**<No definition. */
    00135     hsSndSyncStop, /**<No definition. */
    00136     hsSndChargerAttach, /**<No definition. */
    00137     hsSndChargerDetach, /**<No definition. */
    00138     hsSndRadioOn, /**<No definition. */
    00139     hsSndRadioOff, /**<No definition. */
    00140     hsSndBatFull, /**<No definition. */
    00141     hsSndBatLow, /**<No definition. */
    00142     hsSndBatShutdown, /**<No definition. */
    00143     hsSndDeepWake, /**<No definition. */
    00144     hsSndDeepSleep, /**<No definition. */
    00145     hsSndRadioInServiceArea, /**<No definition. */
    00146     hsSndRadioOutServiceArea /**<No definition. */
    00147
    00148 };
    00149
    00150 /** Holds beep tone type. @see hsSndSysBeepTag */
    00151 typedef UInt8 hsSndSysBeepType;
    00152
    00153 /**
    00154  * @name Sound mode volume controls
    00155  *
    00156  * Use with HsSndGetUserVolume and HsSndSetUserVolume.
    00157  */
    00158 /*@{*/
    00159 #define hsSndMode_Current               ((HsSndMode) 0x0000) /**<Pass to spefify the currently active sound mode. */
    00160 #define hsSndMode_Receiver              ((HsSndMode) 0x0001) /**<Mode when Radio audio goes to receiver speaker. */
    00161 #define hsSndMode_Speakerphone          ((HsSndMode) 0x0002) /**<Mode when Radio audio goes to loud speaker (speaker phone) */
    00162 #define hsSndMode_SpeakerHost           ((HsSndMode) 0x0003) /**<Mode when radio is off and speaker used exclusively by system and third party audio. */
    00163 #define hsSndMode_Headset               ((HsSndMode) 0x0004) /**<Mode when any audio goes to a mono headphones. */
    00164 #define hsSndMode_Headphones            ((HsSndMode) 0x0005) /**<Mode when any audio goes to stereo headphones. */
    00165 #define hsSndMode_HeadphonesHost        ((HsSndMode) 0x0006) /**<Mode when radio is off and headphones used exclusively by system and third party audio. */
    00166 #define hsSndMode_Carkit                ((HsSndMode) 0x0007) /**<Mode when wired carkit is attached and active to the device.*/
    00167 #define hsSndMode_Reserved              ((HsSndMode) 0x0008) /**<Reserved for future definition. Do not use. */
    00168 /*@}*/
    00169
    00170 /** Holds audio mode type */
    00171 typedef Int16 HsSndMode;
    00172
    00173 /**
    00174  * @name Tone type parameter
    00175  *
    00176  */
    00177 /*@{*/
    00178 #define hsSndToneType_Square            0  /**<Used when calling HsSndTonePlay. */
    00179 /*@}*/
    00180
    00181 /**
    00182  * Sound command values
    00183  *
    00184  * The HsSndCmdType is used as the first parameter to the
    00185  * function HsSndFormatPlay.  Use these command values.
    00186  */
    00187 enum HsSndCmdEnumTag
    00188 {
    00189     hsSndCmdPlay = 1,   /**<Use to initiate a playback session. */
    00190     hsSndCmdStop        /**<Use to terminate the current playback session. */
    00191
    00192 };
    00193
    00194 /** Holds sound command type */
    00195 typedef UInt16 HsSndCmdType;
    00196
    00197 /** Holds sound port ID information. */
    00198 typedef UInt32 HsSndPortID;
    00199
    00200 /** Holds sound switch ID information. */
    00201 typedef UInt32 HsSndSwitchID;
    00202
    00203 /** Used as a parameter to HsSndPortSetParam function. */
    00204 typedef UInt16 HsSndParam;
    00205
    00206 /** Used as a parameter to HsSndSwitchGetParam function. */
    00207 typedef UInt16 HsSndPortClass;
    00208
    00209 /** Holds sound format type */
    00210 typedef UInt16 HsSndFormatType;
    00211
    00212 #define hsSndBayID_AC97                 0x01000000 /**<An AC97 compatible chip is supported as the analog sound patch bay. */
    00213
    00214 /**
    00215  * @name Utility Macros - I
    00216  *
    00217  */
    00218 /*@{*/
    00219 #define HS_AC97(n)                      ((n) | hsSndBayID_AC97) /**<Associates the AC97 Bay ID with other element IDs */
    00220 #define HS_RDIO(n)                      ((n) | hsSndBayID_Radio) /**<Associates the Radio Bay ID (hsSndBayID_Radio) with other element IDs */
    00221 #define HsSndParamValue_SetWithLock(v)  (((v) & ~hsSndParamMode_Mask) | hsSndParamMode_LockParam) /**<Adds LockParam to parameter value. */
    00222 #define HsSndParamValue_SetWithUnlock(v)(((v) & ~hsSndParamMode_Mask) | hsSndParamMode_UnlockParam) /**<Adds UnLockParam to parameter value. */
    00223 #define HsSndParamValue_RemoveMode(v)   (((v) & 0x8000)? (v) | hsSndParamMode_Mask : (v) & ~hsSndParamMode_Mask) /**<Removes LockParam or UnLockParam from parameter value. */
    00224 /*@}*/
    00225
    00226 /**
    00227  * @name Sound switch configuration types
    00228  *
    00229  * Used with HsSndSwitchID.
    00230  */
    00231 /*@{*/
    00232 #define hsSndSwitchID_InRadioSpkr       HS_AC97(0x00010000) /**<Controls the destination port for data coming from the Radio. */
    00233 #define hsSndSwitchID_OutRadioMic       HS_AC97(0x00020000) /**<Controls the source microphone to connect to the Radio. */
    00234 #define hsSndSwitchID_InMic             HS_AC97(0x00030000) /**<Test control for Mfg to directly connect Mic input into any destination speaker. */
    00235 #define hsSndSwitchID_InHostPlay        HS_AC97(0x00040000) /**<Controls which speaker to direct PalmOS audio to.*/
    00236 #define hsSndSwitchID_OutHostRec        HS_AC97(0x00050000) /**<Controls from which port to digitize and send to PalmOS for recording. */
    00237 /*@}*/
    00238
    00239 /**
    00240  * @name Sound port configuration types
    00241  *
    00242  * Used with HsSndPortID.
    00243  */
    00244 /*@{*/
    00245 #define hsSndPortID_Off                 0x00000000 /**<Special meta port ID used to turn off a sound switch. */
    00246 #define hsSndPortID_Current             HS_AC97(0x00000000) /**<Special meta port ID used to specify currently active user port. */
    00247 #define hsSndPortID_OutReceiver         HS_AC97(0x00000001) /**<Receiver speaker. */
    00248 #define hsSndPortID_OutSpeaker          HS_AC97(0x00000002) /**<Back speaker for system audio and speakerphone functions, */
    00249 #define hsSndPortID_OutHeadset          HS_AC97(0x00000003) /**<Audio output to mono headset (right channel output).  Left can be used as input. */
    00250 #define hsSndPortID_OutHeadphones       HS_AC97(0x00000004) /**<Configures the headset port for full left and right stereo output, no inputs. */
    00251 #define hsSndPortID_OutSpeakerAuto      HS_AC97(0x00000005) /**<Automatic port, according to headset insertion. Use with hsSndSwitchID_InRadioSpkr. */
    00252 #define hsSndPortID_InLineRec           HS_AC97(0x00000006) /**<Configures headset jack as input, precluding headset use (special port for test purposes). */
    00253 #define hsSndPortID_InBaseMic           HS_AC97(0x00000007) /**<Microphone at the base of the smartphone body. */
    00254 #define hsSndPortID_InHeadsetMic        HS_AC97(0x00000008) /**<Microphone on a mono headset. Ccomes from left channel as input. */
    00255 #define hsSndPortID_InMicAuto           HS_AC97(0x00000009) /**<Atomatic port, according to headset insertion. Use with hsSndSwitchID_OutRadioMic. */
    00256 #define hsSndPortID_OutRadioMic         HS_AC97(0x0000000A) /**<Output connected to the Radio microphone input. */
    00257 #define hsSndPortID_InRadioSpkr         HS_AC97(0x0000000B) /**<Input from the Radio speaker output. */
    00258 #define hsSndPortID_OutHostRec          HS_AC97(0x0000000C) /**<Output to the Host digitized recording input. */
    00259 #define hsSndPortID_InHostPlay          HS_AC97(0x0000000D) /**<Input from the Host converted to analog for output to speakers. */
    00260 #define hsSndPortID_OutBtHeadset        HS_AC97(0x0000000E) /**<Output port used by InRadioSpkr switch to put Call in bluetooth headset mode. */
    00261 #define hsSndPortID_OutBtHandsfree      HS_AC97(0x0000000F) /**<Output port used by InRadioSpkr switch to put Call in bluetooth handsfree mode. */
    00262 #define hsSndPortID_InHostBaseMic       HS_AC97(0x00000010) /**<Input port that controls source base port for host recording. */
    00263 #define hsSndPortID_InHostHeadsetMic    HS_AC97(0x00000011) /**<Input port controlling source headset port for host recording. */
    00264 #define hsSndPortID_InHostPhone         HS_AC97(0x00000012) /**<Input port used by host if phone or TTY is active. */
    00265 #define hsSndPortID_InCarkit            HS_AC97(0x00000013) /**<Input port used when wired carkit is activated. */
    00266 #define hsSndPortID_OutCarkit           HS_AC97(0x00000014) /**<Output port used when wired carkit is activated. */
    00267 #define hsSndPortID_InBtHeadset         HS_AC97(0x00000015) /**<Input port used by OutRadioMic switch to get uplink audio from BT headset. */
    00268 #define hsSndPortID_InBtHandsfree       HS_AC97(0x00000016) /**<Input port used by OutRadioMic switch to get uplink audio from BT handsfree mode. */
    00269 #define hsSndPortID_LastPort            HS_AC97(0x00000016) /**<Update at end. Same ID as last defined port in sequence. */
    00270 /*@}*/
    00271
    00272 /**
    00273  * @name RadioBayID
    00274  */
    00275 /*@{*/
    00276 #define hsSndBayID_Radio                0x02000000 /**<A defined patch bay for Telephony use. */
    00277 /*@}*/
    00278
    00279 /**
    00280  * @name Sound switch configuration type for Radio patch bay
    00281  *
    00282  * Used with HsSndSwitchID.
    00283  */
    00284 /*@{*/
    00285 #define hsSndSwitchID_RadioCall         HS_RDIO(0x00010000) /**<Keeps track of the audio connection of a Radio call. */
    00286 /*@}*/
    00287
    00288 /**
    00289  * @name Sound port configuration type for hsSndSwitchID_RadioCall
    00290  *
    00291  *  hsSndPortID_Off is already defined for all patch bays.  Use it to turn off the switch indicating no radio call connected.
    00292  */
    00293 /*@{*/
    00294 #define hsSndPortID_ConnectCall         HS_RDIO(0x00000020) /**<Virtual port to indicate a radio call is now connected. */
    00295 /*@}*/
    00296
    00297 /**
    00298  * @name Sound port classes
    00299  *
    00300  * Used when passing a HsSndPortClass parameter in HsSndSwitchGetPort and HsSndSwitchSetPort functions.
    00301  */
    00302 /*@{*/
    00303 #define hsSndPortClass_Virtual          ((UInt16) 0) /**<Symbolic port definition that applies to any port. Use for portID save and restore operations. */
    00304 #define hsSndPortClass_Real             ((UInt16) 1) /**<Current physical port. Use to change port parameters. Applies only to actual ports, not "auto" ports. */
    00305 #define hsSndPortClass_BaseDefault      ((UInt16) 2) /**<Default port to use when restoring a Built-In port (For example, user unplugged headset while "auto" port was enabled.) */
    00306 #define hsSndPortClass_Anchor           ((UInt16) 3) /**<Use to obtain the fixed port in a switch that doesn't change--the port that is patched to other ports. Valid only with HsSndSwitchGetPort.  */
    00307 /*@}*/
    00308
    00309 /**
    00310  * @name Sound parameters
    00311  *
    00312  * Used when passing a parameter of type HsSndParam.
    00313  */
    00314 /*@{*/
    00315 #define hsSndParam_Volume               ((UInt16) 1) /**<Changes the volume of a port */
    00316 #define hsSndParam_Mute                 ((UInt16) 2) /**<Change the mute state of a port. */
    00317 #define hsSndParam_Boost                ((UInt16) 3) /**<Changes the boost state of a port. */
    00318 #define hsSndParam_Pan                  ((UInt16) 4) /**<Change the panning value of a port. */
    00319 /*@}*/
    00320
    00321 /**
    00322  * @name Sound parameter expansion macros
    00323  *
    00324  * Used to add sound parameter values for additional sound parameter control.  For example, muteState = HsSndParamValue_SetWithLock(hsSndMute_Enable);.
    00325  */
    00326 /*@{*/
    00327 #define hsSndParamMode_Mask             0x7000  /**<The 3 upper bits after the sign bit in parameter values are reserved for the parameter mode. */
    00328 #define hsSndParamMode_Normal           0x0000  /**<Default parameter mode allowing parameter to be changed with any other hsSndParamMode. */
    00329 #define hsSndParamMode_LockParam        0x4000  /**<Limits parameter so it can only be changed with hsSndParamMode_LockParam or hsSndParamMode_UnlockParam. */
    00330 #define hsSndParamMode_UnlockParam      0x2000  /**<Removes hsSndParamMode_LockParam so it can be changed with any other hsSndParamMode. */
    00331 /*@}*/
    00332
    00333
    00334 /**
    00335  * @name Mute parameters
    00336  * Used to enable or disable a hsSndParam_Mute parameter.
    00337  */
    00338 /*@{*/
    00339 #define hsSndMute_Enable                1   /**<Activates mute on a port. */
    00340 #define hsSndMute_Disable               0   /**<Disables mute on a port. */
    00341 /*@}*/
    00342
    00343 /**
    00344  * @name Boost parameters
    00345  *
    00346  * Used to enable or disable a hsSndParam_Boost parameter.
    00347  */
    00348 /*@{*/
    00349 #define hsSndBoost_Enable               1   /**<Activates boost on a port. */
    00350 #define hsSndBoost_Disable              0   /**<Disables boost on a port. */
    00351 /*@}*/
    00352
    00353 /**
    00354  * @name Pan parameters
    00355  *
    00356  * Used as special hsSndParam_Pan parameters otherwise use actual Pan value.
    00357  */
    00358 /*@{*/
    00359 #define hsSndPan_Middle                 ((Int16) 0x0000) /**<Pan at midpoint between left and right. */
    00360 #define hsSndPan_Right                  ((Int16) 0x7FFF) /**<Pan all the way to the right.  Cannot use with hsSndParamMode (defaults to Normal mode). */
    00361 #define hsSndPan_Left                   ((Int16) 0x8000) /**<Pan all the way to the left.  Cannot use with hsSndParamMode (defaults to Normal mode). */
    00362 #define hsSndPan_RightNormal            ((Int16) 0x07FF) /**<Pan all the way to the right. Can use with any hsSndParamMode. */
    00363 #define hsSndPan_LeftNormal             ((Int16) 0x0800) /**<Pan all the way to the left.  Can use with any hsSndParamMode. */
    00364 /*@}*/
    00365
    00366 /**
    00367  * @name Sound port flag settings
    00368  *
    00369  * Used with the "flags" variable in HsSndPortInfo structure.
    00370  */
    00371 /*@{*/
    00372 #define hsSndPortFlags_Enabled          0x00000001  /**<Port is enabled and in use. */
    00373 #define hsSndPortFlags_Disabled         0x00000000  /**<Port is disabled. */
    00374 #define hsSndPortFlags_EnableMask       0x00000001  /**<No definition. */
    00375
    00376 #define hsSndPortFlags_MuteOn           0x00000002  /**<Volume is muted. */
    00377 #define hsSndPortFlags_MuteOff          0x00000000  /**<Volume is as specified. (Not muted). */
    00378 #define hsSndPortFlags_MuteMask         0x00000002  /**<No definition. */
    00379
    00380 #define hsSndPortFlags_TypeDigital      0x00000004  /**<Sound data through port is digital. */
    00381 #define hsSndPortFlags_TypeAnalog       0x00000000  /**<Sound data through port is analog. */
    00382 #define hsSndPortFlags_TypeMask         0x00000004  /**<No definition. */
    00383
    00384 #define hsSndPortFlags_BoostOn          0x00000008  /**<Boost control on port is active. */
    00385 #define hsSndPortFlags_BoostOff         0x00000000  /**<Boost control on port is inactive. */
    00386 #define hsSndPortFlags_BoostMask        0x00000008  /**<No definition. */
    00387
    00388 #define hsSndPortFlags_CanInputOnly     0x00000000  /**<Port is for sound input exclusively. */
    00389 #define hsSndPortFlags_CanOutputOnly    0x00000010  /**<Port is for sound output exclusively. */
    00390 #define hsSndPortFlags_CanIOSelect      0x00000020  /**<Port can switch between being for sound input or output. */
    00391 #define hsSndPortFlags_CanIOBothways    0x00000030  /**<Port can be for sound input and output simultaneously. */
    00392 #define hsSndPortFlags_CanIOMask        0x00000030  /**<No definition. */
    00393
    00394 #define hsSndPortFlags_InputOn          0x00000040  /**<Port as sound input is enabled. */
    00395 #define hsSndPortFlags_InputOff         0x00000000  /**<Port as sound input is disabled. */
    00396 #define hsSndPortFlags_InputMask        0x00000040  /**<No definition. */
    00397
    00398 #define hsSndPortFlags_OutputOn         0x00000080  /**<Port as sound output is enabled. */
    00399 #define hsSndPortFlags_OutputOff        0x00000000  /**<Port as sound output is disabled. */
    00400 #define hsSndPortFlags_OutputMask       0x00000080  /**<No definition. */
    00401
    00402 #define hsSndPortFlags_CanMute_Yes      0x00000100  /**<Port has mute control available. */
    00403 #define hsSndPortFlags_CanMute_No       0x00000000  /**<Port has no mute control. */
    00404 #define hsSndPortFlags_CanMuteMask      0x00000100  /**<No definition. */
    00405
    00406 #define hsSndPortFlags_CanBoost_Yes     0x00000200  /**<Port has boost control available. */
    00407 #define hsSndPortFlags_CanBoost_No      0x00000000  /**<Port has no boost control. */
    00408 #define hsSndPortFlags_CanBoostMask     0x00000200  /**<No definition. */
    00409
    00410 #define hsSndPortFlags_CanPan_Yes       0x00000400  /**<Port has pan control available. */
    00411 #define hsSndPortFlags_CanPan_No        0x00000000  /**<Port has No pan control. */
    00412 #define hsSndPortFlags_CanPanMask       0x00000400  /**<No definition. */
    00413
    00414 #define hsSndPortFlags_CanVol_Yes       0x00000800  /**<Port has volume control available. */
    00415 #define hsSndPortFlags_CanVol_No        0x00000000  /**<Port has No volume control. */
    00416 #define hsSndPortFlags_CanVolMask       0x00000800  /**<No definition. */
    00417
    00418 #define hsSndPortFlags_Mute_Locked      0x00001000  /**<If locked, can only be changed with lock/unlock mute parameter changes. */
    00419 #define hsSndPortFlags_Mute_Unlocked    0x00000000  /**<Mute can be changed with any type of mute parameters. */
    00420 #define hsSndPortFlags_Mute_LockMask    0x00001000  /**<No definition. */
    00421
    00422 #define hsSndPortFlags_Boost_Locked     0x00002000  /**<If locked, can only be changed with lock/unlock boost parameter changes/ */
    00423 #define hsSndPortFlags_Boost_Unlocked   0x00000000  /**<Boost can be changed with any type of boost parameters. */
    00424 #define hsSndPortFlags_Boost_LockMask   0x00002000  /**<No definition. */
    00425
    00426 #define hsSndPortFlags_Pan_Locked       0x00004000  /**<If locked, can only be changed with lock/unlock pan parameter changes. */
    00427 #define hsSndPortFlags_Pan_Unlocked     0x00000000  /**<Pan can be changed with any type of pan parameters. */
    00428 #define hsSndPortFlags_Pan_LockMask     0x00004000  /**<No definition. */
    00429
    00430 #define hsSndPortFlags_Vol_Locked       0x00008000  /**<If locked, can only be changed with lock/unlock volume parameter changes. */
    00431 #define hsSndPortFlags_Vol_Unlocked     0x00000000  /**<Volume can be changed with any type of volume parameters. */
    00432 #define hsSndPortFlags_Vol_LockMask     0x00008000  /**<No definition. */
    00433 /*@}*/
    00434
    00435 /**
    00436  * @brief Holds sound port information.
    00437  */
    00438 typedef struct
    00439 {
    00440     UInt32      signature;   /**< Always set to hsSndPortInfo_Signature. */
    00441     UInt32      flags;       /**< Control and information about port. */
    00442     HsSndPortID portID;      /**< Identifies the portID. */
    00443     Int16       minVol;      /**< Bottom value of the volume range.*/
    00444     Int16       maxVol;      /**< Top value of the volume range.*/
    00445     Int16       unityVol;    /**< Volume value when there is no gain or dampening.*/
    00446     Int16       stepVol;     /**< Step size for volume changes within vol range.*/
    00447     Int16       currentVol;  /**< Tracks current volume setting.*/
    00448     Int16       currentPan;  /**< Pan control (0 is midpoint pan between L and R) max pan = maxVol - minVol. */
    00449     UInt16      stepDB;      /**< How many dBs per step = (stepDB >> 8) / (stepDB & 0x0F). */
    00450     UInt16      boostDB;     /**< How many dBs with boost = (boostDB >> 8) / (boostDB & 0x0F). */
    00451     UInt16      reserved1;   /**< Reserved field, set to zero */
    00452     UInt16      reserved2;   /**< Reserved field, set to zero */
    00453 } HsSndPortInfo, *HsSndPortInfoPtr;
    00454
    00455
    00456 /**
    00457  * @name Command flag settings
    00458  *
    00459  * Used with the "Commandflags" parameter in HsSndFormatPlay function.
    00460  */
    00461 /*@{*/
    00462 #define hsSndCmdFlags_noWait        0x00000001  /**< Use wait period for the play command. */
    00463 #define hsSndCmdFlags_yesWait       0x00000000  /**< No wait period for the play command. */
    00464 #define hsSndCmdFlags_waitMask      0x00000001 /**<No definition. */
    00465 /*@}*/
    00466
    00467
    00468 /**
    00469  * Sound formats
    00470  */
    00471 enum HsSndFormatEnumTag
    00472 {
    00473     hsSndFormatMidi = 2, /**<Midi format. */
    00474     hsSndFormatAmr, /**<Obsolete.  Use Codec Plug-in Manager or streaming component. */
    00475     pmSndFormatSetAttackEnvID, /**<For internal use only (escape code used by PmSndStreamSetAttackEnvID macro function). */
    00476     pmSndFormatPauseStream, /**<For internal use only (escape code used by PmSndStreamPause macro function). */
    00477     pmSndFormatResumeStream, /**<For internal use only (escape code used by PmSndStreamResume macro function). */
    00478     pmSndFormatSetStoppable /**<For internal use only (escape code used by PmSndStreamStoppable macro function). */
    00479 };
    00480
    00481
    00482 /**
    00483  * @name Sound buffer flag settings
    00484  *
    00485  * Used with the "flags" parameter in HsSndBufferData.
    00486  */
    00487  /*@{*/
    00488 #define hsSndBufFlags_canInterrupt        0x0001 /**< Playback can be interrupted by user events. */
    00489 #define hsSndBufFlags_cannotInterrupt     0x0000 /**< (Default) Playback cannot be interrupted by user events. */
    00490 #define hsSndBufFlags_interruptMask       0x0001 /**<No definition. */
    00491
    00492 #define hsSndBufFlags_yesRepeat           0x0002 /**< Repeat the buffer using the "repeat" count in HsSndBufferData.controls. */
    00493 #define hsSndBufFlags_noRepeat            0x0000 /**< (Default) Buffer used only once. */
    00494 #define hsSndBufFlags_repeatMask          0x0002 /**<No definition. */
    00495
    00496 #define hsSndBufFlags_yesEndDelay         0x0004 /**< Delay completion of playback using the "delay" count in HsSndBufferData.controls. */
    00497 #define hsSndBufFlags_noEndDelay          0x0000 /**< (Default) No delay after last batch of audio data processed. */
    00498 #define hsSndBufFlags_endDelayMask        0x0004 /**<No definition. */
    00499
    00500 #define hsSndBufFlags_attackEnvNone       0x0000 /**< (Default) No attack envelope to be used. */
    00501 #define hsSndBufFlags_attackEnvRings      0x0010 /**< Use special attack envelope style suitable for call ringtones. */
    00502 #define hsSndBufFlags_attackEnvVibeNone   0x0020 /**< Use special attack envelope with initial vibration before envelope */
    00503 #define hsSndBufFlags_attackEnvVibeRings  0x0030 /**< Use special attack envelope for ringtones with initial vibration before envelope */
    00504 #define hsSndBufFlags_attackEnvRings2     0x0040 /**< Use type 2 attack envelope suitable for call ringtones (stright ramp up) */
    00505 #define hsSndBufFlags_attackEnvReserved1  0x0050 /**< Reserved for future use. Do Not use */
    00506 #define hsSndBufFlags_attackEnvVibeRings2 0x0060 /**< Use type 2 attack enveloper with initial vibration before envelope */
    00507 #define hsSndBufFlags_attackEnvReserved2  0x0070 /**< Reserved for future use. Do Not use */
    00508 #define hsSndBufFlags_attackEnvMask       0x00F0 /**< Mask reserves up to 16 different envelope IDs. */
    00509
    00510 #define hsSndBufFlags_interruptDefault    0x0000 /**< (Default) interrupt sound on most user events if hsSndBufFlags_canInterrupt flag is set. */
    00511 #define hsSndBufFlags_interruptPhone      0x0100 /**< interrupt on user events (except Touch, Navigation arrows and pens down). */
    00512 #define hsSndBufFlags_interruptModeMask   0x0300 /**< Mask reserves 2 bits for up to 4 different interrupt modes. */
    00513 /*@}*/
    00514
    00515 /**
    00516  * @name Buffer amplitude settings
    00517  *
    00518  * Used with HsSndBufferData.amplitude field.
    00519  */
    00520 /*@{*/
    00521 #define hsSndAmplitude_silent           ((UInt32) 0)    /**< Minimum volume value used to silent a port */
    00522 #define hsSndAmplitude_unity            ((UInt32) 1024) /**< Volume value used to pass through sound without amplification or attenuation. */
    00523 /*@}*/
    00524
    00525 /******************************************************************************/
    00526 /* HsSndBufferProc */
    00527 /**
    00528    @brief Callback function used under various conditions with sound.
    00529
    00530    @param userdata      IN  Userdata passed when setting the callback routine
    00531    @param flags         IN  Copy of the HsSndBufferData flags field
    00532    @param buffer        IN  Pointer originally passed in HsSndBufferData
    00533    @param bytesUsed     OUT How many bytes have been consumed from the buffer
    00534    @param time          OUT Number of milliseconds available for callback processing
    00535
    00536    @return              Error code.
    00537
    00538 *******************************************************************************/
    00539 typedef Err (*HsSndBufferProc)  (void * userdata, UInt32 flags,
    00540                                  void * buffer, UInt32 bytesUsed, UInt32 time);
    00541
    00542 /**
    00543  * @brief Holds sound buffer information.
    00544  *
    00545  * When using the hsSndCmdPlay command in function HsSndFormatPlay,
    00546  * you should pass a pointer to a properly filled HsSndBufferData
    00547  * structure. This structure provides information about the buffer
    00548  * of coded audio data that is going to be processed and played.
    00549  */
    00550 typedef struct HsSndBufferData
    00551 {
    00552     UInt32          signature;  /**<Always set to hsSndBufferData_Signature or error returned. */
    00553     UInt32          flags;      /**<Flags and status bits for the buffer. Use the hsSndBufferFlags_* symbols appropriately.  Set any undefined or unused flags to zero.*/
    00554     UInt32          amplitude;  /**<Volume level for playback. (Valid range from 0 to hsSndAmplitude_unity.)*/
    00555     void *          buffer;     /**<Pointer to beginning of coded audio data to process and/or play. */
    00556     UInt32          bufferSize; /**<Size in bytes of the buffer of coded audio data. */
    00557     HsSndBufferProc progress_callback; /**<When Not NULL, is invoked at regular intervals. If progress_callback returns an error, then the play session terminates.*/
    00558     void *          progress_userdata; /**<Passed to progress_callback when invoked. */
    00559     HsSndBufferProc completion_callback; /**<When Not NULL, it will be invoked when buffer processing completed. */
    00560     void *          completion_userdata; /**<Passed to completion_callback when invoked. */
    00561
    00562    /**
    00563     * Compound field with repeat count and end delay controls.
    00564     * Use HsSndBufControl_Set* macros with this field. Repeat Field: valid range from 1 to 254,
    00565     * or hsSndBufControl_repeatForever (255). The processing of the buffer will be looped
    00566     * according to this number. When repeatForever is used, then termination should be
    00567     * done by returning an error code from the progress callback. Alternatively,
    00568     * for non-blocking playback, the caller may issue another "Play" call with the "Stop"
    00569     * command. This field is valid and non-zero when hsSndBufFlags_yesRepeat is set
    00570     * in the buffer flags, otherwise this field must be set to zero. A repeat value of 1
    00571     * means play one time. Values of 2 and greater will perform the requested number of
    00572     * playbacks by looping on the same buffer data. Use HsSndBufControl_SetRepeat macro to set
    00573     * values in this field. endDelay fld:  Valid range from 1 to 255, each unit is a
    00574     * 1/50th second delay. Use HsSndBufControl_SetEndDelay macro to set values in this field.
    00575     * This field is valid and non-zero when hsSndBufFlags_yesEndDelay is set in the buffer
    00576     * flags, otherwise this field must be set to zero.
    00577     */
    00578     UInt32          controls;
    00579     UInt32          reserved1;  /**<reserved, must set to zero*/
    00580     UInt32          reserved2;  /**<reserved, must set to zero*/
    00581
    00582 } HsSndBufferData;
    00583
    00584
    00585 #define hsSndMidiMsg_SetVolume  1
    00586
    00587
    00588 #if CPU_ENDIAN == CPU_ENDIAN_BIG
    00589     #define hsSndMidiProgressMsg_Signature  'MidP'
    00590 #else
    00591     #define hsSndMidiProgressMsg_Signature  'PdiM' /* 'MidP' char array as UInt32 little endian */
    00592 #endif
    00593 typedef struct HsSndMidiProgressMsg
    00594 {
    00595     UInt32      signature;
    00596     UInt32      msgType;
    00597     UInt32      param1;
    00598     UInt32      param2;
    00599
    00600 } HsSndMidiProgressMsg;
    00601
    00602
    00603 #if CPU_ENDIAN == CPU_ENDIAN_BIG
    00604     #define hsSndPortInfo_Signature 'SPRT'
    00605 #else
    00606     #define hsSndPortInfo_Signature 'TRPS' /* "SPRT" char array as UInt32 little endian */
    00607 #endif
    00608
    00609 #if CPU_ENDIAN == CPU_ENDIAN_BIG
    00610     #define hsSndBufferData_Signature   'SBDA'
    00611 #else
    00612     #define hsSndBufferData_Signature   'ADBS' /* 'SBDA' as little endian UInt32 */
    00613 #endif
    00614
    00615 /**
    00616  * @name Buffer control macros
    00617  *
    00618  * Use these macros to set or get the proper control in
    00619  * HsSndBufferData.controls field.
    00620  */
    00621 /*@{*/
    00622 #define HsSndBufControl_SetRepeat(controls, value)   (controls = ((controls & 0xFFFFFF00) |  (((UInt32) value) & 0xFF)      ))
    00623 #define HsSndBufControl_GetRepeat(controls)          (controls & 0x000000FF)
    00624 #define HsSndBufControl_SetEndDelay(controls, value) (controls = ((controls & 0xFFFF00FF) | ((((UInt32) value) & 0xFF) << 8)))
    00625 #define HsSndBufControl_GetEndDelay(controls)        ((controls & 0x0000FF00) >> 8)
    00626 #define hsSndBufControl_repeatForever                (0xFF)
    00627 /*@}*/
    00628
    00629
    00630 // ===============================================================================================
    00631 // Gain Envelope Feature Support
    00632 // ===============================================================================================
    00633 /**
    00634  * @name Gain Envelope Definitions
    00635  *
    00636  * Used as attackEnvID parameter to function PmSndStreamSetAttackEnvID.
    00637  */
    00638  /*@{*/
    00639 #define pmSndAttackEnvIDRings       (hsSndBufFlags_attackEnvRings)      /**< The ringtone attack envelope ramp-up to low volume initially, and to full volume after about 4 seconds */
    00640 #define pmSndAttackEnvIDVibeRing    (hsSndBufFlags_attackEnvVibeRings)  /**< Vibrate for 4 seconds, then behave as pmSndAttackEnvIDRings */
    00641 #define pmSndAttackEnvIDRings2      (hsSndBufFlags_attackEnvRings2)     /**< The ringtone attack envelope ramp-up in about 1 second */
    00642 #define pmSndAttackEnvIDVibeRing2   (hsSndBufFlags_attackEnvVibeRings2) /**< Vibrate for 4 seconds, then behave as pmSndAttackEnvIDRings2 */
    00643
    00644
    00645 // ===============================================================================================
    00646 // Sound Preference Definitions (compatible with SndBayID and SndPortID)
    00647 // ===============================================================================================
    00648 #define pmSndBayID_AUDP                 0x0F000000 /**< we are reserving SndBayID 15 for audio preference purposes */
    00649
    00650 #define PM_AUDP_CLASS_MASK              0x4000
    00651 // Utility macro to associate special port class marker to this IDs (so we can use it as an HsSndPortClass parameter)
    00652 #define PM_AUDP_CLASS(n)                ((n) | PM_AUDP_CLASS_MASK) /**< utility to associate preferences class marker to prefIDs */
    00653
    00654 #define pmSndPrefID_AppsGroupHoldType   PM_AUDP_CLASS(0x0001) /**< specify how to hold application audio (mute/pause) */
    00655 #define pmSndPrefID_JackOutIfMicUnused  PM_AUDP_CLASS(0x0002) /**< shall we force jack out to stereo if Mic not in use? */
    00656 #define pmSndPrefID_PhoneRxGainLimit    PM_AUDP_CLASS(0x0003) /**< set if gain-limit phone Rx to receiver speaker */
    00657 #define pmSndPrefID_WakeOnAnswerBtn     PM_AUDP_CLASS(0x0004) /**< set to be able to wake device when headset answer button is pressed */
    00658 #define pmSndPrefID_AudioTable          PM_AUDP_CLASS(0x0005) /**< pass pointer to PmSndGain8Table to load for use, pass zero to return to default */
    00659 #define pmSndPrefID_GsmMccArray         PM_AUDP_CLASS(0x0006) /**< pass pointer to PmSndGsmMccArray to load for use, pass zero to return to default */
    00660 #define pmSndPrefID_AthenaActive        PM_AUDP_CLASS(0x0007) /**< set to activate audio paths to multi-connector, clear to return to normal (used for wired carkit mode) */
    00661 #define pmSndPrefID_SleepMode           PM_AUDP_CLASS(0x0008) /**< set to zero for normal sleep, other values for partial audio sleep modes (for internal use only) */
    00662 #define pmSndPrefID_AGCEvent            PM_AUDP_CLASS(0x0009) /**< set to temporarily activate AGC if required (only useful when AGC has been disabled before hand) */
    00663 #define pmSndPrefID_AthenaAudio         PM_AUDP_CLASS(0x000A) /**< set to activate or deactivate automatic routing of audio to Athena connector */
    00664
    00665 typedef UInt16  PmSndPrefID;
    00666
    00667 // Parameters to use with pmSndPrefID_WakeOnAnswerBtn
    00668 #define pmSndPref_WakeOnAnswerBtn_Disable   (0) /**< disable wake up on answer button feature */
    00669 #define pmSndPref_WakeOnAnswerBtn_Enable    (1) /**< enable  wake up on answer button feature */
    00670
    00671 // Parameters to use with pmSndPrefID_AthenaActive
    00672 #define pmSndPref_AthenaActive_No           (0) /**< disable routing to Athena path for automatic switches */
    00673 #define pmSndPref_AthenaActive_Yes          (1) /**< enable routing to Athena path for automatic switches */
    00674
    00675 // Parameters to use with pmSndPrefID_AthenaAudio
    00676 #define pmSndPref_AthenaAudio_NoRouting     (0)  /**< no athena audio routing when Athena audio connection detected. Handled elsewhere or through pmSndPrefID_AthenaActive */
    00677 #define pmSndPref_AthenaAudio_IfMicPresent  (16) /**< when Athena audio class detected, only route if Mic is also present */
    00678 #define pmSndPref_AthenaAudio_Unconditional (32) /**< cause unconditional audio routing if Athena audio class detected */
    00679
    00680 // Utility macro to associate the hsSndBayID_Radio to other elements
    00681 #define PM_AUDP(n)                      ((n) | pmSndBayID_AUDP) /**< utility to associate the Preference Bay ID with other element ID */
    00682
    00683 // Use these for HsSndSwitchID in the Preferences patch bay
    00684 #define pmSndSwitchID_Preferences       PM_AUDP(0x00400000) /**< used with the HsSoundLib Switch calls to set and get sound preference data */
    00685
    00686
    00687 // ===============================================================================================
    00688 // Media Synchronization Definitions
    00689 // ===============================================================================================
    00690 typedef UInt32   PmClkTickRef;
    00691
    00692 #define pmAudioClkTickRef   ((PmClkTickRef) 0x00000001) /**< use as PmClkTickRef when requiring audio tick clock */
    00693
    00694 #endif // __HSSOUNDLIB_COMMON__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