Interface: ISpeechRecognizer
Type: Hidden

GetPropertyNumber Method

The GetPropertyNumber method returns a numeric value specified by the named key.

The speech recognition (SR) engine maintains several changeable values for setting the characteristics of the SR process. These controls, or properties, are listed in pairs with the control name and an associated value. For example, the SAPI 5 SR engine defines a property allocating CPU usage for the SR engine. This property is named ResourceUsage, and has a range of 0 to 100 percent. The default value is 50. This number is the percentage of the CPU time allocated for SR processing. This value may be changed to increase or decrease the processing time for SR features.

To get the current value, call ISpeechRecognizer.GetPropertyNumber. To set a new value, call ISpeechRecognizer.SetPropertyNumber. In addition, a PropertyNumberChange event is sent after the change is made. This event is broadcast to all applications set to receive it. Since multiple applications, or even recognition contexts within the same application can use the same SR engine, the applications may need to react to the new settings appropriately. Applications should restrict making changes unless there is a compelling reason. Changes to the engine properties will take effect at the next synchronization point. The changes persist in the engine until properties are changed again.

Persisting the changes on a permanent basis is an engine design issue. There is no requirement to do so and each engine manufacturer may implement changing characteristics differently. See the manufacturer's engine documentation for specific details. The SAPI 5 engine changes are not permanent beyond the life span of the recognizer object. That is, when all the applications using the same recognizer object (essentially an SR engine) quit, the values will return to the default state.

If properties need to be changed in a SAPI 5 engine, use Speech properties in Control Panel. For instance, the AdaptationOn property controlling background and continuous adaptation of speech recognition is the same property as Background Adaptation in Settings for the Recognition Profile on the Speech Recognition tab.

Properties are not required of SR engines and each manufacturer's engine may be different. Consult the manufacturer's documentation for specific information.

SpeechRecognizer.GetPropertyNumber(
     Name As String,
     Value As Long
) As Boolean

Parameters

Name

Specifies the string name of the property.

Value

Specifies the value associated with the property Name. This value is passed back upon successful completion of the call. If the return value is False, Value will not be updated.

Return Value

A Boolean variable of True if the property is supported, or False if not supported.

Remarks

For a complete list of SAPI 5 supported properties, see the SAPI 5 SR Properties White Paper.

Example

The following Visual Basic form code demonstrates the use of the SetPropertyNumber method, GetPropertyNumber method, and PropertyNumberChange event.

To run this code, create a form with the following controls:

• Two command buttons called Command1 and Command2

Paste this code into the Declarations section of the form.

Clicking Command1 displays the current value of the property. The second button increments the value by one and the new value is displayed as a result of the PropertyNumberChange event. The original or starting value will be the same as the Accuracy vs. Recognition Response Time slider in the Recognition Profile Settings in the Speech properties of Control Panel.

Option Explicit

Const THE_PROPERTY = "ResourceUsage"
Public WithEvents RC As SpSharedRecoContext
Public myGrammar As ISpeechRecoGrammar

Private Sub Command1_Click()
    On Error GoTo EH

    Dim lActualValue As Long
    Dim fSupported As Boolean
    Dim T As String

    fSupported = RC.Recognizer.GetPropertyNumber(THE_PROPERTY, lActualValue)
    T = "Property's current value: " & lActualValue
    MsgBox T, vbInformation

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Command2_Click()
    On Error GoTo EH

    Dim lActualValue As Long
    Dim fSupported As Boolean

    With RC.Recognizer
        fSupported = .GetPropertyNumber(THE_PROPERTY, lActualValue)
        fSupported = .SetPropertyNumber(THE_PROPERTY, lActualValue + 1)
    End With

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Form_Load()
    On Error GoTo EH
    Set RC = New SpSharedRecoContext

    Set myGrammar = RC.CreateGrammar
    myGrammar.DictationSetState SGDSActive

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub RC_PropertyNumberChange _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal PropertyName As String, _
    ByVal NewNumberValue As Long)

    On Error GoTo EH
    MsgBox "Property's value has been incremented by 1.", vbInformation

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Dim T As String

    T = "Desc: " & Err.Description & vbNewLine
    T = T & "Err #: " & Err.Number
    MsgBox T, vbExclamation, "Run-Time Error"
    End

End Sub