ToneIndicator Class (POS for .NET v1.12 SDK Documentation)
2/27/2008
Defines the programmatic interface for a UPOS Tone Indicator device.
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Syntax
'Declaration
Public MustInherit Class ToneIndicator
Inherits PosCommon
public abstract class ToneIndicator : PosCommon
public ref class ToneIndicator abstract : 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 that may be the computer system speaker or another hardware device. Frequently the computer speaker is not available or is in a position that is inaudible to the operator.
Sound a 2-tone indicator, providing simple pitch and volume control.
Provide a synchronous 1-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 computer standard speaker. Many POS systems have such devices (for example, an ICL 92R keyboard) so that an indicator is always present at the point of sale.
This device supports a 2-tone sound so that "siren" tones can be produced. The indicator is generally also started asynchronously so applications can perform other functions while they wait for the user to acknowledge the tone. There are also options to start the tone asynchronously without a count so that it runs forever, and can be stopped when it runs.
When the indicator is started asynchronously, an OutputCompleteEvent event is raised when all the tones have been played. This enables 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 bit 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 raises an OutputCompleteEvent event. A parameter of this event contains the OutputId of the completed request.
The Sound method does not return an error status because of a hardware problem. These errors are only reported by an ErrorEvent event. 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 occur because of an application error, while the last is a system resource exception.
If an error occurs while it performs an asynchronous request, an ErrorEvent event 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 events are not raised for cleared output. This method also stops any output that may be in progress (when it is possible).
Device Sharing
The Tone Indicator is a shareable device. Its device-sharing rules are as follows:
After the application opens and enables 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 raised to all 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 starts asynchronous sounds is the only one that receives the corresponding OutputCompleteEvent event or ErrorEvent event.
If a scenario exists in such a way 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 middle of a synchronous Sound method, it returns the Claimed property 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 stopped.
Example
The following example sets up an asynchronous 2-tone indicator and sounds it 100 times. Each tone is sounded for 750 milliseconds at 50 percent volume, without a 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, because 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 the InterToneWait property. 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.