SpObjectToken GetStorageFileName method (SAPI 5.3)

Microsoft Speech API 5.3

Object: SpObjectToken
Type: Hidden

GetStorageFileName Method

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

  
    SpObjectToken.GetStorageFileName(
     ObjectStorageCLSID As String,
     KeyName As String,
     FileName As String,
     Folder As SpeechTokenShellFolder) As String

Parameters

• ObjectStorageCLSID
  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.
• KeyName
  The name of the attribute file for the registry entry of clsidCaller. This attribute stores the location of the resource file.
• FileName
  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.
• Folder
  One or more SpeechTokenShellFolder constants specifying the Folder.

Return Value

A String variable containing the path of the storage file.

Example

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 ""

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