Gauge: dsd_fsx_xml_sound.gau
Although its name refers to FSX, this gauge will also work in FS2004.  It is heavily based on dsd_xml_sound3.gau.

Panel.cfg syntax
gauge10=dsd_fsx_xml_sound!Sound,  2,2,2,2,./gauges/dsd_xml_sound.ini
gauge11=dsd_fsx_xml_sound!Debugger,  420,550,600,80

The most important change in gauge function is the way it handles volume settings.  Previous versions of the gauge used a range from 0 to 100 to get/set volume levels.  I have changed this to the range used by DirectSound, -10000 (representing very, very quiet) to 0 (representing full volume).  If this change is going to cause you problems with your existing code, you can set a variable (L:Old Volume Control) to force the gauge back to the old method of handling volume settings.  See below.

For those who havent used earlier versions of the gauge, each sound is controlled by a separate XML L:Variable (hereinafter referred to as an LVar.)   You control the sound by setting the control variable (LVar) to the value that corresponds to the action you want.  You assign LVars to sounds using a configuration file.  Specify the configuration file in panel.cfg, as a fifth parameter for the Sound gauge element  see the example above.  In FSX, there are two procedures you may follow when specifying your configuration file.

1.	You specify a relative path by starting it with a dot  see the sample syntax, above.  This dot effectively anchors us in the main FS folder.  In the example above, the .ini file is located in the main FS gauges folder, and it is called dsd_xml_sound.ini.  You are not limited to the FS gauges folder, you may specify any folder you like  Your only challenge is ensuring the end user has the folder you specify in their FS folder system.

2.	Alternatively, in FSX SP2 or later, you may construct an absolute path to your configuration file.  SimConnect allows us to look up the path to the currently operating .air file.  By stripping off the name of the .air file itself, we are left with the path to the specific folder where the aircraft is installed.  To this path name, you will add the specific folder and file name for your configuration file.  For example, my usual test aircraft is installed in a folder called:
D:\fsx\Aircraft\b777_300
Specifying a configuration file thusly:
gauge37=dsd_fsx_xml_sound!Sound,  2,2,2,2,\panel\dsd_fsx_test_sound.ini
will result in a configuration specification of 
D:\fsx\Aircraft\b777_300\panel\dsd_fsx_test_sound.ini  placing the configuration file in the aircrafts panel folder, where gauges are typically installed nowadays.
To install the configuration file in the aircrafts topmost folder, beside the .air file and the aircraft.cfg file, you would use a specification like this:
gauge37=dsd_fsx_xml_sound!Sound,  2,2,2,2, \YourConfigurationFile.ini

Please note that with this method, there is no dot at the beginning of the panel.cfg parameter string, but that there must be a / or \ character to specify a folder.  The gauge will treat the / and \ characters equivalently.  If the gauge does not find one of these three characters at the beginning of the parameter string, it will use the default value for the configuration file name (./Gauges/dsd_xml_sound.ini)  You will get a MessageBox warning you of this action.

In FS9, and in FSX if the gauge cannot establish a link to SimConnect, only the first method will work.

Creating the Configuration File
The configuration file is used for a number of things.  The most important of these is establishing paring between the sounds you want to play and the LVars you will use to control those sounds.  If you look at the sample .ini file listing at the end of this document, you will find that it contains three section headings.  Of these, one is labeled [Sounds] and one is labeled [LVars].  Each has a listing of numbered entries.  The numbering is how the link between sound and LVar is established.  Please note that that is the only significance to the numbering of the entries.  The sound at entry Sound00 is matched with the LVar at Lvar00, the sound at entry Sound01 is matched with the LVar at Lvar01, etc.
As you may have gathered by now, in specifying LVars in the configuration file, you just supply the bare name.  You do not add L: at the beginning, or ,number at the end.   This has nothing to do with how you will access the variables in XML, it is only relevant to the way a C/C++ gauge works with these variables.
When you are creating entries for the sounds themselves in your configuration file, you can, if you wish, specify a volume to be applied to the sound when it is loaded.  See the first two sound entries in the sample .ini file below.  This option is useful if you, or the end user of your product, feel a particular sound or sounds, as recorded, are too loud.  You can specify the volume to be used and thus not have to bother setting it within your gauge.  Specifying a volume setting in this way will not preclude you from changing the volume level later. 
When you are specifying sounds in the configuration file, you have the same two options for specifying a sound name as you do for specifying the configuration file name.  You can use a relative path (starting with a dot and referring to a folder within the FS folder tree) or you can construct an absolute path, using the path to the aircrafts .air file as a base ( by specifying a \ or / as the first character of the parameter string.  See the first sound setting in the sample .ini file below.  It specifies a folder called PanelSounds, located within the aircrafts panel folder, as the location for the sound file.  Again, if the sound file name string specified does start with either a dot or one of the two slash characters, the gauge will use the default name for that sound entry.
The settings in the third group, [Config] are each reviewed later.

Working with sounds
To control a given sound, it is just a matter of setting its corresponding LVar to the value listed below for the action you want:
1 (&gt;L:SomeXMLControlVar, number)  will play the sound once, with no changes made to volume or pan settings.
0 (&gt;L:SomeOtherXMLControlVar, number)   will stop the sound if it is playing.
8 (&gt;L:YetAnotherXMLControlVar, number)  will first retrieve the current volume and pan input settings.  It will then apply them to the sound in question, and finally, with start playing the sound in looping mode.

Gauge control variables can use the following values:
	0 - Stop Sound
	1 - Play sound once, without changing the existing volume or pan settings.
	2 - Play sound as a loop, without changing the existing volume or pan settings.
	3 - Set the sound's volume, using the setting found in the specified VolumeIn variable, see below.
	4 - Get the sound's current volume setting, placing it in the specified VolumeOut variable.
	5 - Set the sound's pan, using the setting found in the specified PanIn variable.
	6 - Get the sound's current pan setting, placing it in the specified PanOut variable.
	7 - Play sound once, but first set the volume and pan to the settings found in the VolumeIn and PanIn variables.
	8 - Play sound as a loop, but first set the volume and pan to the settings found in the VolumeIn and PanIn variables.
	9 - Get sound's looping status.  Will return 1 if a playing sound is looping, 0 if the sound is in play once mode or is not playing at all.
	10  Unload a sound.  Sounds will be automatically unloaded on gauge exit, but if the sound file is large, and you are done with it, you might want to unload it immediately, and reclaim the memory.

In the Config Section of the .ini file, the following items can be set.  They are all shown with their corresponding default values.

MaxSounds=10
The default is 10, but the maximum is now 1000. (Yes, you read that right!)  I can't see anyone using that many, but the memory is allocated dynamically now, so there is no harm in the very high limit.  It will allow dedicated users to avoid loading more than one instance of the gauge in the same panel.  I have seen that happen.  Keeping the maximum to the number of sounds you will actually use will minimize both CPU and memory use by the gauge.

ErrorFlag= -1
In the event of some kind of error occurring, the gauge's control variable will be set to this value.  The default is -1.  You can pick any integer value you like, except the range from 1 to 99, which is reserved for actual commands.  The gauge now has several Windows Message Boxes built in that will appear in the event of an error.  I expect that the only one you will ever see will occur if the gauge does not find a sound file specified in the .ini file.  In order to ease problem solving, it will inform the user which file was not found.  If an error does occur, any further changes to that sound's control variable will be ignored.  Other sounds will be processed however.

GlobalCommands=DSDGlobals
You can set this variable to 3 meaningful values.
	1 - stops all sounds currently playing.
	2 - mutes all sounds.  It set's their volume to -10000, but does not stop them from actually playing.
	3 - unmutes all sounds previously muted.  It restores their previously stored volume settings.
In each case, the variable will be reset to 0.

VolumeVarIn=dsd_xml_sound_volume_in
Use this variable to specify the volume setting for use with the SetVolume command (3).  Volume is specified as a value between 0 (full volume) and -10000 (100 db attenuation, inaudible.)  In practice, any setting less than about -3000 (30 db attenuation) will be inaudible.

PanVarIn=dsd_xml_sound_pan_in
Use this variable to specify the pan setting for use with the SetPan command (5).  Pan is specified as a value between -10000 (full left) and 10000 (full right).  0 is centered.

VolumeVarOut=dsd_xml_sound_volume_out
Use this variable to receive the volume setting retrieved with the GetVolume command (4).

PanVarOut=dsd_xml_sound_pan_out
Use this variable to receive the pan setting retrieved with the GetPan command (6).

LoopOut=dsd_xml_sound_loop_out
Use this variable to receive the loop setting retrieved with the Get Looping Status command (9).

VolumePlayed=dsd_volume_played
This variable will automatically receive the volume setting used when the last play sound command was issued.  Note that this volume level may no longer apply - it may have been changed with the SetVolume command.

PanPlayed=dsd_pan_played
This variable will automatically receive the pan setting used when the the last play command was issued.  Note that this pan setting may no longer apply - it may have been changed with the SetPan command.

LoopPlayed=dsd_loop_played
This variable will automatically receive the loop setting used when the last play command was issued.

Other LVARS, names not selectable:

FSSoundIsOn: 
In both FS9 and FSX, this variable will return 1 if FS's sounds are active and 0 if they are not.  The gauge's own sounds will follow FS sound status - they will mute if FS's sound is off or if the sim is paused.

Old Volume Control:
Settable.  If set to 1, the gauge will use the old volume range of 0 to 100, with 100 representing full volume and 0 representing fully muted.  If set to 0, the gauge will use the actual DirectSound range, which is -10000 for fully muted, to 0, which represents full volume.  Note that if the gauge encounters positive values for volumes in the [Sounds] section of the .ini file, it will presume that you want to use the old range and will set this variable accordingly.  For the technically inclined, the DirectSound range represents attenuation in 100ths of decibels, so the value of -10000 represents an attenuation of 100 decibels.  Don't change this variable once it is set - bad things will happen.

FSVersion:
Returns 9 for FS2004 and 10 for FSX.  Supplied in case you want to use any version specific code in your own gauges. 

SimConnected:
FSX Only.  Returns 1 if a link to SimConnect was established and 0 if it was not.

FSSimIsPaused:
Returns 1 if the simulation is paused, and 0 if it is not. 

SoundIsMuted:
In both FS9 and FSX, this variable will return 1 if the gauge has muted its own sounds and 0 if the sounds are not muted.

UserMutedSounds
In both FS9 and FSX, this variable will return 1 if an XML gauge has muted the sounds by setting the GlobalCommands variable to a value of 2.  While individual sounds will able to be unmuted by setting their volume levels, sounds will not automatically unmute with a change in sound variable or pause status.  You will need to manually unmute by setting the Global Commands variable to 3.  If sounds have not been so muted, the variable will have a value of zero.

ViewSystemStatus:
FSX Only.  Retrieved via SimConnect.
0  Outside (spot) view.
1  2D cockpit view
2  3D VC view
4  Orthogonal (map) view

ViewSystemMessages:
FSX Only.  Default value is zero.  If set to a non-zero value, the ViewSystemStatus value, above, will be published in a Windows Message Box, each time it changes.  Obviously, for experimentation only.

TimeOfDay:
FS2004 Only.  Returns the otherwise broken Time of Day variable.

Example .ini:
With the exception of the first two entries in the [Sounds] section, the following example illustrates default values that the gauge will use in the absence of a user specified value, or in the absence of a configuration file altogether. The first Sound entry illustrates the specification of a sound located within a folder named PanelSounds, with this folder being located within the aircrafts panel folder.  The first two Sound entries show the specification of a volume value to be assigned to the sound when it is first loaded by the gauge.

[Config]
MaxSounds=10
GlobalCommands=DSDGlobals
VolumeVarIn=dsd_xml_sound_volume_in
PanVarIn=dsd_xml_sound_pan_in
VolumeVarOut=dsd_xml_sound_volume_out
PanVarOut=dsd_xml_sound_pan_out
LoopOut=dsd_xml_sound_loop_out
VolumePlayed=dsd_volume_played
PanPlayed=dsd_pan_played
LoopPlayed=dsd_loop_played

[Sounds]
Sound00=\panel\PanelSounds\dsd_xml_00.wav, -1500
Sound01=.\Sound\dsd\dsd_xml_01.wav, -2000
Sound02=.\Sound\dsd\dsd_xml_02.wav
Sound03=.\Sound\dsd\dsd_xml_03.wav
Sound04=.\Sound\dsd\dsd_xml_04.wav
Sound05=.\Sound\dsd\dsd_xml_05.wav
Sound06=.\Sound\dsd\dsd_xml_06.wav
Sound07=.\Sound\dsd\dsd_xml_07.wav
Sound08=.\Sound\dsd\dsd_xml_08.wav
Sound09=.\Sound\dsd\dsd_xml_09.wav
Sound100=.\Sound\dsd\dsd_xml_100.wav
Sound999=.\Sound\dsd\dsd_xml_999.wav

[LVars]
Lvar00=dsd_fsx_sound_id_00
Lvar01=dsd_fsx_sound_id_01
Lvar02=dsd_fsx_sound_id_02
Lvar03=dsd_fsx_sound_id_03
Lvar04=dsd_fsx_sound_id_04
Lvar05=dsd_fsx_sound_id_05
Lvar06=dsd_fsx_sound_id_06
Lvar07=dsd_fsx_sound_id_07
Lvar08=dsd_fsx_sound_id_08
Lvar09=dsd_fsx_sound_id_09
LVar100=dsd_fsx_sound_id_100
LVar999=dsd_fsx_sound_id_999
