SpObjectToken GetStorageFileName method (SAPI 5.4)

Speech API 5.4
Microsoft Speech API 5.4

Object: SpObjectToken
Type: Hidden

GetStorageFileName Method

The GetStorageFileName method creates a storage file for data associated with the object token.

     ObjectStorageCLSID As String,
     KeyName As String,
     FileName As String,
     Folder As SpeechTokenShellFolder
) As String


Globally unique identifier (GUID) of the calling object. The method searches the registry for an entry key name of ObjectStorageCLSID, and then a corresponding Files subkey. If the registry entry is not present, one is created.
The name of the attribute file for the registry entry of clsidCaller. This attribute stores the location of the resource file.
A specifier that is either "" or a path/file name for storage file.
  • If this starts with "X:\" or "\\" it is assumed to be a full path; otherwise it is assumed to be relative to special folders given in the nFolder parameter.
  • If it ends with a "\", or is NULL, a unique file name will be created. The file name will be something like: "SP_7454901D23334AAF87707147726EC235.dat". "SP_" and ".dat" are the default prefix name and file extension name. The numbers in between are generated guid number to make sure the file name is unique.
  • If the name contains a %d the %d is replaced by a number to give a unique file name. The default file extension is .dat, the user can specify anything else. Intermediate directories are created.
  • If a relative file is used, the value stored in the registry includes the nFolder value as %nFolder% before the rest of the path.
One or more SpeechTokenShellFolder constants specifying the Folder.

Return Value

A String variable containing the path of the storage file.


The following Visual Basic form code demonstrates the GetStorageFileName and RemoveStorageFileName methods. To run this code, create a form with no controls and paste the code into the Declarations section of the form.

The operations performed in this example can best be viewed with REGEDIT.EXE. For a discussion of Registry issues, please see the ISpeechDataKey interface.

The Example code does the following:

  • Creates a new SpObjectToken object and sets its ID property to a new subfolder called Demo within the Voices\Tokens folder. The True parameter of the SetId call forces the creation of this folder, if it does not already exist.
  • Creates a data key object that references the new Demo folder and uses the data key to write a value into the folder.
  • Calls the GetStorageFileName method. After this call, the Demo folder contains a subfolder called {CDD1141B-82FB-405c-99BE-69A793A92D87}. This is the CLSID used as a parameter of the GetStorageFileName method. Within this is a folder called Files, which contains the storage file path in a value called Demo.
  • Calls the RemoveStorageFileName method to delete the storage file and remove the Demo value from the Files folder.
  • Uses the ISpeechDataKey.Remove method to delete the {CDD1141B-82FB-405c-99BE-69A793A92D87} folder and Demo folders.

Option Explicit

Private Sub Form_Load()
    On Error GoTo EH

    Dim C As SpeechLib.SpObjectTokenCategory
    Dim ID As String
    Dim K As SpeechLib.ISpeechDataKey           '
    Dim SF As String
    Dim T As SpeechLib.SpObjectToken
    Dim TestCLSID As String

    TestCLSID = "{CDD1141B-82FB-405c-99BE-69A793A92D87}"

    ' Create new category object, set it to Voices category:
    Set C = New SpObjectTokenCategory
    C.SetId SpeechCategoryVoices

    ' Create new token object, and set its ID
    ' to the path of a folder which does not exist
    ' ("True" parameter creates the folder):
    Set T = New SpObjectToken
    ID = SpeechCategoryVoices & "\Tokens\Demo"
    T.SetId ID, , True

    ' Set data key object to demo voice's
    ' folder and write a CLSID value:
    Set K = T.DataKey
    K.SetStringValue "CLSID", TestCLSID

    ' Create storage file for token.
    SF = T.GetStorageFileName(TestCLSID, "Demo", _
        vbNullString, STSF_FlagCreate + STSF_AppData)
    MsgBox SF, vbInformation

    ' Remove storage file.
    Call T.RemoveStorageFileName(TestCLSID, "Demo", True)

    ' Remove "{CDD1141B-82FB-405c-99BE-69A793A92D87}"
    ' folder and "Demo" folder
    T.Remove TestCLSID
    T.Remove ""

    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 Sub