ISpObjectToken::GetStorageFileName (SAPI 5.3)

Microsoft Speech API 5.3

ISpObjectToken::GetStorageFileName

ISpObjectToken::GetStorageFileName retrieves the object token file name from the registry.

  
    HRESULT GetStorageFileName(
    REFCLSID      clsidCaller,
    LPCWSTR      *pszValueName,
    LPCWSTR      *pszFileNameSpecifier,
    ULONG         nFolder,
    LPWSTR      **ppszFilePath
);
  

Parameters

• clsidCaller
  [in] Globally unique identifier (GUID) of the calling object. The registry is searched for an entry key name of clsidCaller, and then a corresponding "Files" subkey. If the registry entry is not present, one is created.

• pszValueName
  [in] The name of the attribute file for the registry entry of clsidCaller. This attribute stores the location of the resource file.

• pszFileNameSpecifier
  [in] The specifier that is either NULL 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 being used the value stored in the registry includes the nFolder value as %nFolder% before the rest of the path.

• nFolder
  [in] A CSIDL value that identifies the folder whose path is to be retrieved. The user can force the creation of a folder by combining the folder's CSIDL with CSIDL_FLAG_CREATE. If pszFileNameSpecifier is NULL or "\", nFolder must have a specified CSIDL folder combined with CSIDL_FLAG_CREATE if the user wants to force to create the file.

• ppszFilePath
  [out] Address of a pointer to the null-terminated string that receives the file path information. Must be freed when no longer required.

Return values

Value

S_OK

E_POINTER

E_OUTOFMEMORY

S_FALSE

E_INVALIDARG

SPERR_UNINITIALIZED

SPERR_TOKEN_DELETED

FAILED(hr)

Example

The following code snippet creates and removes two token objects for two test files.

  
// Declare local identifiers:
HRESULT                   hr = S_OK;
CComPtr<ISpObjectToken>   cpObjectToken;
GUID                      guid0;
GUID                      guid1;
WCHAR                     *cpFileName;
WCHAR                     *cpFileName2;
ULONG                     CSIDL_LOCAL_APPDATA = 28;
ULONG                     CSIDL_FLAG_CREATE = 32768;

// Get the default text-to-speech engine token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken;);

if (SUCCEEDED (hr))
{
   hr = CoCreateGuid(&guid0;);
}

if (SUCCEEDED (hr))
{
   hr = CoCreateGuid(&guid1;);
}

if (SUCCEEDED (hr))
{
   // Create file with default format and store it in folder that
   // contains application-specific data that does not roam.
   hr = cpObjectToken->GetStorageFileName(guid0, L"TestFile", NULL, CSIDL_FLAG_CREATE|CSIDL_LOCAL_APPDATA, &cpFileName;);
}

if (SUCCEEDED (hr))
{
   // Remove object token.
   hr = cpObjectToken->Remove(&guid0;);
}

if (SUCCEEDED (hr))
{
   // Create file to be stored under C:\Program Files and that is to
   // have name like MyData "7412341D23334A7321707145534EC235.dump.
   hr = cpObjectToken->GetStorageFileName(guid1, L"TestFile2", L"c:\\Program Files\\MyData%d.dump", CSIDL_FLAG_CREATE, &cpFileName2;);
}
if (SUCCEEDED (hr))
{
   // Remove object token.
   hr = cpObjectToken->Remove(&guid1;);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}