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 | Description |
---|---|
S_OK | Function completed successfully. |
E_POINTER | ppszFilePath is invalid or bad. |
E_OUTOFMEMORY | Exceeded available memory. |
S_FALSE | A new file was created. |
E_INVALIDARG | pszValueName is invalid or bad. |
SPERR_UNINITIALIZED | Either the data key or the token delegate interface is uninitialized. |
SPERR_TOKEN_DELETED | Key has been deleted. |
FAILED(hr) | Appropriate error message. |
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.
}