ToneIndicator Class
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Usage
'Usage
Dim toneIndicator1 As New ToneIndicator()
Syntax
'Declaration
MustInherit Public Class ToneIndicator
Inherits PosCommon
public abstract class ToneIndicator : PosCommon
public abstract ref class ToneIndicator : public PosCommon
public abstract class ToneIndicator extends PosCommon
public abstract class ToneIndicator extends PosCommon
Remarks
Capabilities
The Tone Indicator service object has the following capabilities:
Sound a tone device, which may be the PC system speaker or another hardware device. In many cases the PC speaker is not available or is in a position that is inaudible to the operator.
Sound a two-tone indicator, providing simple pitch and volume control.
Provide a synchronous one-shot (play once while waiting) indicator, similar to the Win32 Beep function.
Model
The Tone Indicator device is for use when the POS hardware platform provides such capabilities external to the PC standard speaker. Many POS systems have such devices, for example the ICL 92R keyboard, so that an indicator is always present at the point of sale.
This device supports a two-tone sound so that “siren” tones can be produced. The indicator is in general also started asynchronously so applications can perform other functions while waiting for the user to acknowledge the tone. There are also options to start the tone asynchronously with no count, so it runs forever, and can be stopped when running.
When the indicator is started asynchronously then an OutputCompleteEvent is fired when all the tones have been played. This allows the application to know that the tone has stopped. For example, when the cash drawer is opened the tone can be started quietly for a given number of cycles. If the cash drawer is closed, the tone is stopped explicitly by the application; if not, the OutputCompleteEvent enables you to alter the prompt to the operator and possibly restart the tone a little louder.
The Tone Indicator follows the general output model. Asynchronous output is handled as follows:
The service object buffers the request, sets the OutputId property to an identifier for this request, and returns as soon as possible. When the device completes the request successfully, then the service object fires an OutputCompleteEvent. A parameter of this event contains the OutputId of the completed request.
The Sound method does not return an error status due to a hardware problem. These errors are only reported by an ErrorEvent. An error status is returned only if the service object is claimed by another application, is not enabled, a parameter is invalid, or the request cannot be queued. The first three error cases are due to an application error, while the last is a system resource exception.
If an error occurs while performing an asynchronous request, an ErrorEvent is fired.
The service object guarantees that asynchronous output is performed on a first-in first-out basis.
All output buffered by POS for .NET can be deleted by calling the ClearOutput method. OutputCompleteEvents are not fired for cleared output. This method also stops any output that may be in progress (when possible).
Device Sharing
The Tone Indicator is a sharable device. Its device sharing rules are:
After opening and enabling the device, the application can access all properties and methods and receive StatusUpdateEvent events.
If more than one application has opened and enabled the device, all applications can access its properties and methods. StatusUpdateEvent events are fired to all of the applications.
If one application claims the tone indicator, then only that application can call the Sound and SoundImmediate methods. Use of this feature effectively restricts the tone indicator to the main POS application if that application claims the device at startup.
The application that initiates asynchronous sounds is the only one that receives the corresponding OutputCompleteEvent event or ErrorEvent event.
If a scenario exists such that an application is playing a sound and a separate application legally claims the device and plays a sound, then the sound being played from the first application is interrupted. If the first application is in the midst of a synchronous Sound method, it returns Claimed from the method call. If the application has issued an asynchronous Sound method, then no consistent reporting mechanism is possible and the first sound is simply terminated.
Example
The following example sets up an asynchronous two-tone indicator and sounds it 100 times. Each tone is sounded for 750 milliseconds at 50% volume, with no pause between each tone.
Indicator.Tone1Pitch = 500
Indicator.Tone1Volume = 50
Indicator.Tone1Duration = 750
Indicator.Tone2Pitch = 800
Indicator.Tone2Volume = 50
Indicator.Tone2Duration = 750
Indicator.InterToneWait = 0
Indicator.AsyncMode = True
Indicator.Sound 100, 0
The following example starts a synchronous indicator. This has a simple alternating beep, 500 milliseconds on and 500 milliseconds off.
Indicator.Tone1Pitch = 500
Indicator.Tone1Volume = 50
Indicator.Tone1Duration = 500
Indicator.Tone2Pitch = 0' turn off second tone
Indicator.InterToneWait = 0' no wait after tone-1
Indicator.AsyncMode = False
Indicator.Sound 100, 500
The following example causes an error, as it defines both tones to be zero.
Indicator.Tone1Pitch = 0' turn off first tone
Indicator.Tone2Pitch = 0' turn off second tone
Indicator.Sound 100, 0
The indicator Sound method can also be used to start an indefinite duration tone. If the numberOfCycles parameter is specified to be WaitForever then the tone is started and must be stopped explicitly.
Indicator.Tone1Pitch = 500
Indicator.Tone1Volume = 50
Indicator.Tone1Duration = 500
Indicator.Tone2Pitch = 0' turn off second tone
Indicator.InterToneWait = 0' no wait after Tone1
Indicator.AsyncMode = True
Indicator.Sound WaitForever, 500
To stop an outstanding tone you have to use the ClearOutput or SoundImmediate method.
…
Indicator.AsyncMode = True
Indicator.Sound WaitForever, 500
…
Indicator.ClearOutput
or
Indicator.SoundImmediate
There is also a SoundImmediate method that causes both tones to be sounded once with their InterToneWait. The tones are sounded synchronously. This imitates a more normal Beep function such as that provided by the Win32 API.
Indicator.Tone1Pitch = 500
Indicator.Tone1Volume = 50
Indicator.Tone1Duration = 500
Indicator.Tone2Pitch = 0' turn off second tone
Indicator.InterToneWait = 0' no wait after Tone1
Indicator.AsyncMode = True
Indicator.Sound 1, 0' asynchronous beep
Indicator.SoundImmediate' synchronous beep
Inheritance Hierarchy
System.Object
Microsoft.PointOfService.PosDevice
Microsoft.PointOfService.PosCommon
Microsoft.PointOfService.ToneIndicator
Microsoft.PointOfService.BasicServiceObjects.ToneIndicatorBasic
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Platforms
Development Platforms
Windows XP Home Edition, Windows XP Professional, Windows Server 2003, Windows Longhorn, and Windows 2000