ISpObjectToken::GetStorageFileName

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

HRESULT GetStorageFileName(
    REFCLSID      clsidCaller,
    const WCHAR  *pszValueName,
    const WCHAR  *pszFileNameSpecifier,
    ULONG         nFolder,
    WCHAR       **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

Example

The following code snippet creates and removes a token object for a test file.

HRESULT hr;
GUID guid0;
GUID guid1;

CComPtr<ISpObjectToken> cpSpObjectToken;
CSpCoTaskMemPtr<WCHAR> cpFileName;
CSpCoTaskMemPtr<WCHAR> cpFileName2;

hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpSpObjectToken);
//Check return value

ZeroStruct(guid0);

hr = CoCreateGuid(&guid1);
//Check return value

hr = cpSpObjectToken->GetStorageFileName( guid0, L"TestFile", NULL, CSIDL_FLAG_CREATE|CSIDL_APPDATA, &cpFileName);
//The created file will have default format, and will be stored under file system directory that  
//serves as a common repository for application-specific data.
//Check return value

hr = cpSpObjectToken->Remove(&guid0);
//Check return value

hr = cpSpObjectToken->GetStorageFileName(guid1, L"TestFile2", L"c:\\Program Files\\MyData%d.dump", CSIDL_FLAG_CREATE, &cpFileName2);
//The created file will be stored under C:\Program Files, and will have a name like MyData "7412341D23334A7321707145534EC235.dump"
//Check return value
	
hr = cpSpObjectToken->Remove(&guid1);
//Check return value