Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Speech Recognition Manager Reference

Framework
Carbon/Carbon.h
Declared in
SpeechRecognition.h

Overview

The Speech Recognition Manager provides speech recognition support in applications.

Functions by Task

Opening and Closing Recognition Systems

Creating and Manipulating Recognizers

Managing Speech Objects

Traversing Speech Objects

Creating Language Objects

Manipulating Language Objects

Using the System Feedback Window

Creating, Invoking and Disposing UPPs

Functions

DisposeSRCallBackUPP

Disposes of a universal procedure pointer (UPP) to a speech recognition callback function.

void DisposeSRCallBackUPP (
   SRCallBackUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechRecognition.h

InvokeSRCallBackUPP

Invokes your speech recognition callback function.

void InvokeSRCallBackUPP (
   SRCallBackStruct *param,
   SRCallBackUPP userUPP
);

Discussion

You should not have to call the InvokeSRCallbackUPP function, as the system calls your speech recognition callback function for you.

Availability
Declared In
SpeechRecognition.h

NewSRCallBackUPP

Creates a new universal procedure pointer (UPP) to a speech recognition callback function.

SRCallBackUPP NewSRCallBackUPP (
   SRCallBackProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your speech recognition callback function.

Return Value

A UPP to the speech recognition callback function. See the description of the SRCallBackUPP data type.

Availability
Declared In
SpeechRecognition.h

SRAddLanguageObject

Adds a language object to some other language object.

OSErr SRAddLanguageObject (
   SRLanguageObject base,
   SRLanguageObject addon
);

Parameters
base

The language object to which to add the language object specified by the addon parameter.

addon

The language object to add on to the language object specified in the base parameter. For example, if addon specifies a word and base specifies a phrase, then SRAddLanguageObject appends that word to the end of that phrase.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRAddLanguageObject function is useful for adding language objects to phrases, paths, and language models. For a phrase or a path, SRAddLanguageObject appends the specified object to the end of the phrase or path. For a language model, SRAddLanguageObject adds the specified object to the list of alternative recognizable utterances.

The language object to which you add an object acquires a new reference to that object. Accordingly, any changes you subsequently make to the added object are reflected in any object to which you added it. The base object releases its reference to the added object when the base object is disposed of.

SRAddLanguageObject does not alter the value of the reference constant property of the language object specified by the base parameter.

See SRAddText for a useful shortcut function.

Availability
Declared In
SpeechRecognition.h

SRAddText

Adds text to the contents of a language object.

OSErr SRAddText (
   SRLanguageObject base,
   const void *text,
   SInt32 textLength,
   SRefCon refCon
);

Parameters
base

A language object to which to add the text.

text

A pointer to a buffer that contains the words or phrase to add to the contents of the specified language object.

textLength

The size, in bytes, of the specified text.

refCon

An application-defined reference constant. The value of the reference constant property of the new word or phrase representing the specified text is set to this value.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRAddText function is useful for phrases, paths, and language models. If the base parameter specifies a path or language model, SRAddText is equivalent to calling SRNewPhrase, SRAddLanguageObject, and SRReleaseObject for the phrase specified by the text parameter and calling SRSetProperty to reset the value of the reference constant property of the new phrase.

If the base parameter specifies a phrase, SRAddText is equivalent to calling SRNewPhrase, SRAddLanguageObject, and SRReleaseObject for each distinguishable word in the text parameter and calling SRSetProperty to set the value of the reference constant property of the new words.

Availability
Declared In
SpeechRecognition.h

SRCancelRecognition

Cancels the attempt to recognize the current utterance.

OSErr SRCancelRecognition (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRCancelRecognition function instructs the recognizer specified by the recognizer parameter to stop recognizing speech. You need to call either SRContinueRecognition or SRCancelRecognition each time your application is notified that the user has started speaking (using Apple events or through an application-defined callback routine).

Availability
Declared In
SpeechRecognition.h

SRChangeLanguageObject

Changes the contents of a language object.

OSErr SRChangeLanguageObject (
   SRLanguageObject languageObject,
   const void *text,
   SInt32 textLength
);

Parameters
languageObject

A language object.

text

A pointer to a buffer that contains the words or phrase to which the contents of the specified language object are to be changed.

textLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

SRChangeLanguageObject is a convenient shortcut for calling SREmptyLanguageObject and then SRAddText.

SRChangeLanguageObject does not alter the value of the reference constant property of the language object specified by the languageObject parameter.

If there are no other references to the language object specified by the languageObject parameter, calling SRChangeLanguageObject causes that object to be released.

If you want to swap rapidly among several language models, you should use the SRSetLanguageObject function instead of SRChangeLanguageObject. Or, you could use the kSREnabled property to rapidly enable and disable parts of the current language model to reflect the current context.

Availability
Declared In
SpeechRecognition.h

SRCloseRecognitionSystem

Closes a recognition system when your application is finished using it (for example, just before your application quits).

OSErr SRCloseRecognitionSystem (
   SRRecognitionSystem system
);

Parameters
system

A recognition system.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRCloseRecognitionSystem function closes the recognition system specified by the system parameter. If any speech objects are still attached to that recognition system, they are disposed of and any references you have to those objects are thereby rendered invalid.

Availability
Declared In
SpeechRecognition.h

SRContinueRecognition

Causes a recognizer to continue recognizing speech.

OSErr SRContinueRecognition (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

You need to call either SRContinueRecognition or SRCancelRecognition each time your application is notified that the user has started speaking (using Apple events or through an application-defined callback routine).

Availability
Declared In
SpeechRecognition.h

SRCountItems

Determines the number of subitems in a container object.

OSErr SRCountItems (
   SRSpeechObject container,
   long *count
);

Parameters
container

A speech object.

count

On return, a pointer to a long containing the number of subitems in the specified speech object.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

This function is useful only for speech objects that have distinguishable subitems, such as phrases (which contain words), paths (which contain words, phrases, and language models), and language models (which contain words, phrases, paths, and possibly other language models).

Version Notes

In Speech Recognition Manager version 1.5, this function is useful only for operating on language objects (of type SRLanguageObject), although it is defined for all speech objects.

Availability
Declared In
SpeechRecognition.h

SRDrawRecognizedText

Draws recognized text in the feedback window.

OSErr SRDrawRecognizedText (
   SRRecognizer recognizer,
   const void *dispText,
   SInt32 dispLength
);

Parameters
recognizer

A recognizer.

dispText

A pointer to a buffer that contains the text to be drawn.

dispLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRDrawRecognizedText function draws the text specified by the dispText and dispLength parameters in the transcript portion of the feedback window associated with the recognizer specified by the recognizer parameter. The text is drawn in the style characteristic of all recognized text. You might want to use this function to display a recognized phrase using a different spelling than the one used in the language model.

If the value of the kSRWantsResultTextDrawn property of the specified recognizer is TRUE (which is the default value), a transcript of the text of a recognition result is automatically sent directly to the feedback window. As a result, you should call SRDrawRecognizedText only when the value of the recognizer’s kSRWantsResultTextDrawn property is FALSE.

Availability
Declared In
SpeechRecognition.h

SRDrawText

Draws output text in the feedback window.

OSErr SRDrawText (
   SRRecognizer recognizer,
   const void *dispText,
   SInt32 dispLength
);

Parameters
recognizer

A recognizer.

dispText

A pointer to a buffer that contains the text to be drawn.

dispLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRDrawText function draws the text specified by the dispText and dispLength parameters in the transcript portion of the feedback window associated with the recognizer specified by the recognizer parameter. The text is drawn in the style characteristic of all output text.

Availability
Declared In
SpeechRecognition.h

SREmptyLanguageObject

Empties the contents of a language object.

OSErr SREmptyLanguageObject (
   SRLanguageObject languageObject
);

Parameters
languageObject

A language object.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SREmptyLanguageObject function empties the contents of the language object specified by the languageObject parameter. (For example, if languageObject specifies a phrase containing two words, calling SREmptyLanguageObject would result in a phrase that contains no words.) Any properties of that object that are not related to its contents are unchanged. In particular, SREmptyLanguageObject does not alter the value of the reference constant property of that language object.

If there are no other references to the words, phrases, and paths that were contained in the language object, calling SREmptyLanguageObject causes them to be disposed of.

Availability
Declared In
SpeechRecognition.h

SRGetIndexedItem

Gets a subitem in a container object.

OSErr SRGetIndexedItem (
   SRSpeechObject container,
   SRSpeechObject *item,
   long index
);

Parameters
container

A speech object.

item

On return, a reference to the subitem in the specified speech object that has the specified index.

index

An integer ranging from 0 to one less than the number of subitems in the specified speech object. (You can call the SRCountItems function to determine the number of subitems contained in a speech object.) If the index you specify is not in this range, SRGetIndexedItem returns the result code kSRParamOutOfRange.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

This function is useful for iterating through all subitems in a container object.

SRGetIndexedItem increases the reference count of the specified speech object. You should call the SRReleaseObject function to release the object reference returned by SRGetIndexedItem when you are done using it. For example, you can get a reference to the third word in a phrase by executing this code:

myErr = SRGetIndexedItem(myPhrase, &myWord, 2)

Then, when you are finished using the word, you should execute this code:

myErr = SRReleaseObject(myWord);

Version Notes

In Speech Recognition Manager version 1.5, this function is useful only for operating on language objects (of type SRLanguageObject), although it is defined for all speech objects.

Availability
Declared In
SpeechRecognition.h

SRGetLanguageModel

Gets a recognizer’s active language model.

OSErr SRGetLanguageModel (
   SRRecognizer recognizer,
   SRLanguageModel *languageModel
);

Parameters
recognizer

A recognizer.

languageModel

On return, a reference to the language model currently active for the specified recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

SRGetLanguageModel increases the reference count of the specified language model. You should call the SRReleaseObject function to release the language model reference returned by SRGetLanguageModel when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRGetProperty

Gets the current value of a property of a speech object.

OSErr SRGetProperty (
   SRSpeechObject srObject,
   OSType selector,
   void *property,
   Size *propertyLen
);

Parameters
srObject

A speech object.

selector

A property selector. See “Recognizer Properties,” “Recognizer Listen Key Properties,” “Language Object Properties,” and “Recognition System Properties” for lists of the available property selectors.

property

A pointer to a buffer into which the value of the specified property is to be copied.

propertyLen

On entry, a pointer to the length, in bytes, of the specified buffer. If the value is of a fixed size, then propertyLen should point to a variable of type Size that specifies that size. If the size of the value can vary (for example, if the value is a string), then propertyLen should point to a variable of type Size that specifies the number of bytes in the buffer pointed to by the property parameter.

On return, if the buffer is large enough to hold the returned property value and no error occurs, SRGetProperty sets propertyLen to the total number of bytes in the value of the specified property. If the buffer is not large enough to hold the returned property value, SRGetProperty sets propertyLen to the number of bytes required to store the requested property and returns the kSRBufferTooSmall error code.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

Not all selectors are valid for all types of speech objects. If the selector you specify does not specify a property of the specified speech object, SRGetProperty returns the result code kSRCantGetProperty.

If SRGetProperty returns an object reference, you must make sure to release that object reference (by calling SRReleaseObject) when you are finished using it. Most selectors do not cause SRGetProperty to return object references. For example, passing the selector kSRSpelling causes SRGetProperty to return a buffer of text, not an object reference.

Availability
Declared In
SpeechRecognition.h

SRGetReference

Obtains an extra reference to a speech object.

OSErr SRGetReference (
   SRSpeechObject srObject,
   SRSpeechObject *newObjectRef
);

Parameters
srObject

A speech object.

newObjectRef

On return, a new reference to the specified speech object.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The original object reference (contained in srObject) and the new reference (returned in newObjectRef) may have different values. Accordingly, you cannot simply compare two object references to determine whether they are references to the same speech object.

SRGetReference increases the reference count of the specified speech object. You should call the SRReleaseObject function to release the object reference returned by SRGetReference when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRIdle

Grants processing time to the Speech Recognition Manager if your application does not call WaitNextEvent frequently.

OSErr SRIdle (
   void
);

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRIdle function grants processing time to the Speech Recognition Manager, thereby allowing it to process incoming sound and send recognition results.

Most applications do not need to call the SRIdle function. You need to call it only if your application does a significant amount of processing without periodically calling WaitNextEvent. If you do use the SRIdle function, you should call it often enough that the Speech Recognition Manager can perform its work.

Note, however, that if you call SRIdle and not WaitNextEvent, you give time to the recognizer but not to the feedback window. You must call WaitNextEvent periodically to have the feedback animations work correctly if your recognizer is using the standard feedback window.

Availability
Declared In
SpeechRecognition.h

SRNewLanguageModel

Creates a new language model.

OSErr SRNewLanguageModel (
   SRRecognitionSystem system,
   SRLanguageModel *model,
   const void *name,
   SInt32 nameLength
);

Parameters
system

A recognition system.

model

On return, a reference to a new empty language model associated with the specified recognition system.

name

A pointer to a buffer that contains the name of the language model. The name of the language model should be unique among all the language models your application creates, and it should be comprehensible to users. (For example, a language model that defined a list of names might be called “«Names»”).

The convention that language model names begin with the character “«” and end with the character “»” is adopted to support future utilities that display the names of language models to the user (perhaps as part of showing the user what he or she can say).

nameLength

The size, in bytes, of the specified name.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

You can add language objects (that is, words, phrases, paths, and other language models) to a language model by calling the SRAddText and SRAddLanguageObject functions.

SRNewLanguageModel sets the reference count of the specified language model to 1. You should call the SRReleaseObject function to release the language model reference returned by SRNewLanguageModel when you are done using it.

You can get or set the name of an existing language model by calling the SRGetProperty or SRSetProperty functions with the kSRSpelling property selector.

Availability
Declared In
SpeechRecognition.h

SRNewLanguageObjectFromDataFile

Reads a language object from a data file.

OSErr SRNewLanguageObjectFromDataFile (
   SRRecognitionSystem system,
   SRLanguageObject *languageObject,
   short fRefNum
);

Parameters
system

A recognition system.

languageObject

On return, a reference to a new language object whose description is stored in the open data file that has the file reference number specified by the fRefNum parameter.

fRefNum

A file reference number of an open data file.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

SRNewLanguageObjectFromDataFile reads data beginning at the current file mark.

If the language object is successfully created and initialized, the file mark is left at the byte immediately following the language object description. Otherwise, if the language object data is not appropriately formatted, SRNewLanguageObjectFromDataFile returns the result code kSRCantReadLanguageObject as its function result and the file mark is not moved.

You should call the SRReleaseObject function to release the language object reference returned by SRNewLanguageObjectFromDataFile when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRNewLanguageObjectFromHandle

Creates a language object from the handle previously created by the SRPutLanguageObjectIntoHandle function.

OSErr SRNewLanguageObjectFromHandle (
   SRRecognitionSystem system,
   SRLanguageObject *languageObject,
   Handle lObjHandle
);

Parameters
system

A recognition system.

languageObject

On return, a reference to a new language object created and initialized using the private data to which the lobjHandle parameter is a handle.

lObjHandle

A handle to a language object. The data specified by lobjHandle should have been created by a previous call to the SRPutLanguageObjectIntoHandle function; if that data is not appropriately formatted, SRNewLanguageObjectFromHandle returns the result code kSRCantReadLanguageObject as its function result.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

You can use this function to load language objects from resources (for example, by using the Resource Manager function GetResource).

You should call the SRReleaseObject function to release the language object reference returned by SRNewLanguageObjectFromHandle when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRNewPath

Creates a new path.

OSErr SRNewPath (
   SRRecognitionSystem system,
   SRPath *path
);

Parameters
system

A recognition system.

path

On return, a reference to a new empty path associated with the specified recognition system.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

You can then add objects to a path by calling the SRAddText or SRAddLanguageObject functions.

You should call the SRReleaseObject function to release the path reference returned by SRNewPath when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRNewPhrase

Creates a new phrase.

OSErr SRNewPhrase (
   SRRecognitionSystem system,
   SRPhrase *phrase,
   const void *text,
   SInt32 textLength
);

Parameters
system

A recognition system.

phrase

On return, a reference to a new phrase associated with the specified recognition system.

text

A pointer to a buffer that contains the words that comprise the phrase.

textLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The phrase’s contents (that is, the words that comprise the phrase) is specified by the text and textLength parameters. You can, if you wish, create a new empty phrase and then add words to it by calling the SRAddText or SRAddLanguageObject functions.

You should call the SRReleaseObject function to release the phrase reference returned by SRNewPhrase when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRNewRecognizer

Creates a new recognizer.

OSErr SRNewRecognizer (
   SRRecognitionSystem system,
   SRRecognizer *recognizer,
   OSType sourceID
);

Parameters
system

A recognition system.

recognizer

On return, a reference to a new recognizer associated with the specified recognition system and using the specified speech source.

sourceID

A speech source ID. See “Speech Source Constants.”

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

SRNewRecognizer may need to load substantial amounts of data from disk into memory. As a result, you might want to change the cursor to the watch cursor before you call SRNewRecognizer.

You should call the SRReleaseObject function to release the object reference returned by SRNewRecognizer when you are done using it.

Availability
Declared In
SpeechRecognition.h

SRNewWord

Creates a new word.

OSErr SRNewWord (
   SRRecognitionSystem system,
   SRWord *word,
   const void *text,
   SInt32 textLength
);

Parameters
system

A recognition system.

word

On return, a reference to a new word associated with the specified recognition system.

text

A pointer to a buffer that contains the characters that comprise the word.

textLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

You should call the SRReleaseObject function to release the word reference returned by SRNewWord when you are done using it.

Availability
Declared In
SpeechRecognition.h

SROpenRecognitionSystem

Opens a recognition system.

OSErr SROpenRecognitionSystem (
   SRRecognitionSystem *system,
   OSType systemID
);

Parameters
system

On return, a reference to the recognition system having the specified system ID.

systemID

A recognition system ID.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

Generally, you should open a single recognition system when your application starts up and close it (by calling the function SRCloseRecognitionSystem) before your application exits.

Availability
Declared In
SpeechRecognition.h

SRProcessBegin

Indicates that a recognition result is being processed.

OSErr SRProcessBegin (
   SRRecognizer recognizer,
   Boolean failed
);

Parameters
recognizer

A recognizer.

failed

A Boolean value that determines how the feedback gestures are to be altered and whether the response sound is to be played (FALSE) or not (TRUE).

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRProcessBegin function causes the Speech Recognition Manager to provide the relevant feedback (in the feedback window associated with the recognizer specified by the recognizer parameter) indicating that the application is in the process of responding to a spoken command. Currently, the gestures of the feedback character are changed to indicate that processing is occurring.

If you set the value of the recognizer’s kSRWantsAutoFBGestures property to FALSE, you should call SRProcessBegin at the beginning of your response to a recognition result and SRProcessEnd at the end of your response. During the interval separating the two calls, the feedback character displays an appropriate set of gestures showing the user that the task is being processed. If you pass the value TRUE in the failed parameter (indicating that the recognition result cannot successfully be processed), the feedback character displays frowns, shrugs, or other appropriate gestures. In addition, when failed is TRUE, you do not need to call SRProcessEnd to end the processing. If you pass the value FALSE in the failed parameter but determine subsequently that the recognition result cannot successfully be processed, you should call SRProcessEnd with the failed parameter set to TRUE.

If the value of the kSRWantsAutoFBGestures property of the specified recognizer is TRUE, the Speech Recognition Manager calls SRProcessBegin internally before notifying your application of a recognition result, and it calls SRProcessEnd internally after your application is notified. As a result, you should call SRProcessBegin or SRProcessEnd only when the value of the recognizer’s kSRWantsAutoFBGestures property is FALSE.

Because the default value of the kSRWantsAutoFBGestures property is TRUE, most applications do not need to call SRProcessBegin. Calling SRProcessBegin is useful, however, when you know the resulting action might take a significant amount of time.

Availability
Declared In
SpeechRecognition.h

SRProcessEnd

Indicates that a recognition result is done being processed.

OSErr SRProcessEnd (
   SRRecognizer recognizer,
   Boolean failed
);

Parameters
recognizer

A recognizer.

failed

A Boolean value that determines how the feedback gestures are to be altered (FALSE) or not (TRUE).

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRProcessEnd function causes the Speech Recognition Manager to provide the relevant feedback (in the feedback window associated with the recognizer specified by the recognizer parameter) indicating that a recognition result is done being processed. Currently, the gestures of the feedback character are changed and a response sound is played.

If the value of the kSRWantsAutoFBGestures property of the specified recognizer is TRUE, the Speech Recognition Manager calls SRProcessBegin internally before notifying your application of a recognition result, and it calls SRProcessEnd internally after your application is notified. As a result, you should call SRProcessBegin or SRProcessEnd only when the value of the recognizer’s kSRWantsAutoFBGestures property is FALSE.

Because the default value of the kSRWantsAutoFBGestures property is TRUE, most applications do not need to call SRProcessBegin. Calling SRProcessBegin is useful, however, when you know the resulting action might take a significant amount of time.

Availability
Declared In
SpeechRecognition.h

SRPutLanguageObjectIntoDataFile

Puts a language object (and any embedded language objects it contains) into a data file.

OSErr SRPutLanguageObjectIntoDataFile (
   SRLanguageObject languageObject,
   short fRefNum
);

Parameters
languageObject

A language object.

fRefNum

A file reference number of an open data file into which the data describing the specified language object is to be put.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRPutLanguageObjectIntoDataFile function puts a description of the language object specified by the languageObject parameter into the data file specified by the fRefNum parameter. Data are written starting at the current file mark, and the file mark is moved to the end of the written data.

Availability
Declared In
SpeechRecognition.h

SRPutLanguageObjectIntoHandle

Puts a language object (and any embedded languages objects it contains) into a handle.

OSErr SRPutLanguageObjectIntoHandle (
   SRLanguageObject languageObject,
   Handle lobjHandle
);

Parameters
languageObject

A language object.

lobjHandle

A handle to a block of memory into which the data describing the specified language object is to be put. On entry, this handle can have a length of 0.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRPutLanguageObjectIntoHandle function puts a description of the language object specified by the languageObject parameter into the block of memory specified by the lobjHandle parameter. This replaces the data in the handle and resizes the handle if necessary.

You can use Resource Manager functions (such as AddResource) to store language objects into resources.

Availability
Declared In
SpeechRecognition.h

SRReleaseObject

Releases a speech object.

OSErr SRReleaseObject (
   SRSpeechObject srObject
);

Parameters
srObject

A speech object.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

If there are no other remaining references to the object, SRReleaseObject disposes of the memory occupied by the object.

Your application should balance every function call that returns an object reference with a call to SRReleaseObject. This means that every call to a function whose name begins with SRNew or SRGet that successfully returns an object reference must be balanced with a call to SRReleaseObject.

In addition, you should call SRReleaseObject to release references to SRSearchResult objects that are passed to your application (via an Apple event handler or a callback routine).

Availability
Declared In
SpeechRecognition.h

SRRemoveIndexedItem

Removes a subitem from a container object.

OSErr SRRemoveIndexedItem (
   SRSpeechObject container,
   long index
);

Parameters
container

A speech object.

index

An integer ranging from 0 to one less than the number of subitems in the specified speech object. (You can call the SRCountItems function to determine the number of subitems contained in a speech object.) If the index you specify is not in this range, SRRemoveIndexedItem returns the result code kSRParamOutOfRange.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRRemoveIndexedItem function removes from the speech object specified by the container parameter the subitem located at the position specified by the index parameter. If SRRemoveIndexedItem completes successfully, the number of subitems in the container object is reduced by 1, and the index of each subitem that follows the removed item is reduced by 1.

Version Notes

In Speech Recognition Manager version 1.5, this function is useful only for operating on language objects (of type SRLanguageObject), although it is defined for all speech objects.

Availability
Declared In
SpeechRecognition.h

SRRemoveLanguageObject

Removes a language object from another language object that contains it.

OSErr SRRemoveLanguageObject (
   SRLanguageObject base,
   SRLanguageObject toRemove
);

Parameters
base

The language object containing the language object to remove.

toRemove

The language object to remove.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The object specified by the base parameter should be a container one of whose subitems is the object specified by the toRemove parameter.

Availability
Declared In
SpeechRecognition.h

SRSetIndexedItem

Replaces a subitem in a container object with some other object.

OSErr SRSetIndexedItem (
   SRSpeechObject container,
   SRSpeechObject item,
   long index
);

Parameters
container

A speech object.

item

A speech object.

index

An integer ranging from 0 to one less than the number of subitems in the specified speech object.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRSetIndexedItem function replaces the subitem having the index specified by the index parameter in the container object specified by the container parameter with the speech object specified by the item parameter. A reference to the replacement item is maintained separately by the container; as a result, you can release any reference to that item if you no longer need it. The reference to the replaced item is removed from the container; if that reference was the last remaining reference to the object, the object is released.

Version Notes

In Speech Recognition Manager version 1.5, this function is useful only for operating on language objects (of type SRLanguageObject), although it is defined for all speech objects.

Availability
Declared In
SpeechRecognition.h

SRSetLanguageModel

Sets a recognizer’s active language model.

OSErr SRSetLanguageModel (
   SRRecognizer recognizer,
   SRLanguageModel languageModel
);

Parameters
recognizer

A recognizer.

languageModel

The language model you wish to become the active model for the specified recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

If no other references exist to the language model currently in use by the specified recognizer, calling SRSetLanguageModel with a different language model causes the current one to be released.

Availability
Declared In
SpeechRecognition.h

SRSetProperty

Sets the value of a property of a speech object.

OSErr SRSetProperty (
   SRSpeechObject srObject,
   OSType selector,
   const void *property,
   Size propertyLen
);

Parameters
srObject

A speech object.

selector

A property selector. See “Recognizer Properties,” “Recognizer Listen Key Properties,” “Language Object Properties,” and “Recognition System Properties” for lists of the available property selectors.

property

A pointer to a buffer containing the value to which the specified property is to be set.

propertyLen

The length, in bytes, of the specified buffer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRSetProperty function sets the value of the property of the speech object specified by the srObject parameter to the value specified through the property parameter. The selector parameter specifies which property is to be set and the propertyLen parameter specifies it size, in bytes.

Not all properties can be set. If you attempt to set a property that cannot be set, SRSetProperty returns the result code kSRCantSetProperty or kSRBadSelector as its function result.

Availability
Declared In
SpeechRecognition.h

SRSpeakAndDrawText

Draws output text in the feedback window and causes the feedback character in the feedback window to speak that text.

OSErr SRSpeakAndDrawText (
   SRRecognizer recognizer,
   const void *text,
   SInt32 textLength
);

Parameters
recognizer

A recognizer.

text

A pointer to a buffer that contains the text to be drawn and spoken.

textLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Availability
Declared In
SpeechRecognition.h

SRSpeakText

Causes the feedback character in the feedback window to speak a text string.

OSErr SRSpeakText (
   SRRecognizer recognizer,
   const void *speakText,
   SInt32 speakLength
);

Parameters
recognizer

A recognizer.

speakText

A pointer to a buffer that contains the text to be spoken. The text pointed to by the speakText parameter can contain embedded speech commands to enhance the prosody of the spoken string.

speakLength

The size, in bytes, of the specified text.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

While speaking, the feedback character lip-syncs the spoken string using the Speech Synthesis Manager’s phoneme callback routines. SRSpeakText uses the default voice and rate selected in the Speech control panel. (The Speech Synthesis Manager was formerly called the Speech Manager. Its name has been changed to distinguish it from the Speech Recognition Manager and to describe its operation more clearly.)

You can use the SRSpeechBusy function to determine whether the feedback character is already speaking. If it is, you can call the SRStopSpeech function to stop that speaking immediately.

The SRSpeakText function speaks the specified text but does not display it. Use the SRSpeakAndDrawText function if you want to speak and display the text.

Availability
Declared In
SpeechRecognition.h

SRSpeechBusy

Determines if the feedback character in a feedback window is currently speaking.

Boolean SRSpeechBusy (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

On return, true if the feedback character in the feedback window associated with the recognizer specified by the recognizer parameter is currently speaking; otherwise false.

Availability
Declared In
SpeechRecognition.h

SRStartListening

Starts a recognizer listening and reporting results to your application.

OSErr SRStartListening (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRStartListening function instructs the recognizer specified by the recognizer parameter to begin processing sound from its speech source and reporting its results to your application (either using Apple events or through a speech recognition callback routine).

You must already have built a language model and attached it to the recognizer (by calling the SRSetLanguageModel function) before you call SRStartListening.

Availability
Declared In
SpeechRecognition.h

SRStopListening

Stops a recognizer listening and reporting results to your application.

OSErr SRStopListening (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRStopListening function instructs the recognizer specified by the recognizer parameter to stop processing sound from its speech source and reporting its results to your application.

Availability
Declared In
SpeechRecognition.h

SRStopSpeech

Terminates speech by the feedback character in a feedback window.

OSErr SRStopSpeech (
   SRRecognizer recognizer
);

Parameters
recognizer

A recognizer.

Return Value

A result code. See “Speech Recognition Manager Result Codes.”

Discussion

The SRStopSpeech function immediately terminates any speaking by the feedback character in the feedback window associated with the recognizer specified by the recognizer parameter.

Availability
Declared In
SpeechRecognition.h

Callbacks

SRCallBackProcPtr

Defines a pointer to a speech recognition callback function which is called whenever the recognizer encounters one of the events specified in its kSRNotificationParam property.

typedef void (*SRCallBackProcPtr) (
   SRCallBackStruct * param
);

If you name your function MySRCallBackProc, you would declare it like this:

void MySRCallBackProc (
   SRCallBackStruct * param
);

Parameters
param

A pointer to a speech recognition callback structure. See SRCallBackStruct for a description of this structure.

Discussion

You can receive notification of recognizer events either by installing an Apple event handler or by installing a speech recognition callback function. In general, you should use an Apple event handler to process recognition notifications. You should use callbacks only for executable code that cannot easily receive Apple events.

You can determine what event caused your function to be called by inspecting the what field of the speech recognition callback structure specified by the param parameter.

Because the Speech Recognition Manager is not fully reentrant, you should not call any of its functions other than SRContinueRecognition or SRCancelRecognition from within your speech recognition callback. Accordingly, your callback should simply queue the notification for later processing by your software (for instance, when it receives background processing time).

If the event is of type kSRNotifyRecognitionBeginning (which occurs only if you request speech-begun notifications), you must call either SRContinueRecognition or SRCancelRecognition before speech recognition can continue. A recognizer that has issued a recognition notification suspends activity until you call one of these two functions.

In general, when your speech recognition callback receives the kSRNotifyRecognitionBeginning notification, it should queue an indication for your main code both to adjust the current language model (if necessary) and to call the SRContinueRecognition function. When your callback receives the kSRNotifyRecognitionDone notification, it should queue an indication for your main code to handle the recognition result passed in the message field of the speech recognition callback structure specified by the param parameter. You should make sure, however, that the message field contains a valid reference to a recognition result by inspecting the status field of that structure; if status contains any value other than noErr, the contents of the message field are undefined.

When your callback is executed, your application is not the current process. As a result, some restrictions apply; for example, the current resource chain might not be that of your application.

Availability
Declared In
SpeechRecognition.h

Data Types

SRCallBackParam

Defines a speech recognition callback parameter structure.

struct SRCallBackParam {
   SRCallBackUPP callBack;
   long refCon;
};
typedef struct SRCallBackParam SRCallBackParam;

Fields
callBack

A UPP for a speech recognition callback function. You can use the function NewSRCallBackUPP to create this UPP.

refCon

An application-defined reference constant. This value is passed to your callback routine in the refcon field of a speech recognition callback structure. You can pass any 4-byte value you wish.

Discussion

If you want to receive recognition notifications using a speech recognition callback routine instead of an Apple event handler, you must change the value of the kSRCallBackParam property of the current recognizer. The value of the kSRCallBackParam property is the address of a callback function parameter structure, defined by the SRCallBackParam data type.

Availability
Declared In
SpeechRecognition.h

SRCallBackStruct

Defines a structure sent to your speech recognition callback function.

struct SRCallBackStruct {
   long what;
   long message;
   SRRecognizer instance;
   OSErr status;
   short flags;
   long refCon;
};
typedef struct SRCallBackStruct SRCallBackStruct;

Fields
what

A notification flag that indicates the kind of event that caused this notification to be issued. This field contains either kSRNotifyRecognitionBeginning or kSRNotifyRecognitionDone. See “Notification Flags” for complete details on the available notification flags.

message

If the value of the status field is noErr and the value of the what field is kSRNotifyRecognitionDone, this field contains a reference to a recognition result. Your callback routine can inspect the properties of this recognition result to determine what the user said.

Note that your callback routine must release this reference (by calling SRReleaseObject) when it is finished using it. If the value of the status field is not noErr, the value of this field is undefined.

instance

A reference to the recognizer that issued this notification. You should not call SRReleaseObject on this recognizer reference in response to a recognition notification.

status

An error code indicating the status of the recognition. If the value of this field is noErr, the message field contains a reference to a recognition result. If the value of this field is kSRRecognitionDone and the value of the what field is kSRNotifyRecognitionDone, the recognizer finished without error but nothing belonging to that recognizer was recognized; in this case, the message field does not contain a reference to a recognition result. If the value of this field is any other value, some other error occurred.

flags

Reserved for use by Apple Computer, Inc.

refCon

An application-defined reference constant. The value in this field is the value you passed in the refcon field of a callback function parameter structure (of type SRCallBackParam).

Discussion

When you receive a notification of recognition results through an application-defined callback function (instead of using an Apple event handler), the Speech Recognition Manager sends your callback function a pointer to a speech recognition callback structure, defined by the SRCallBackStruct data type.

For information on writing a speech recognition callback function, see SRCallBackProcPtr.

Availability
Declared In
SpeechRecognition.h

SRCallBackUPP

Defines a universal procedure pointer (UPP) to a speech recognition callback function.

typedef SRCallBackProcPtr SRCallBackUPP;

Availability
Declared In
SpeechRecognition.h

SRLanguageModel

Represents a language model.

typedef SRLanguageObject SRLanguageModel;

Discussion

A language model is a list of zero or more words, phrases, or paths.

Availability
Declared In
SpeechRecognition.h

SRLanguageObject

Represents a language object.

typedef SRSpeechObject SRLanguageObject;

Discussion

A language model is built using four kinds of objects, collectively called language objects: words, phrases, paths, and languag