ISpObjectToken::GetStorageFileName

  • Article

This method gets 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] GUID of the calling object. The registry is searched for an entry key name of clsidCaller, and then a corresponding subkey of "Files". If the registry entry is not present, one is created.

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

  • pszFileNameSpecifier
    [in] Pointer to the file name specifier, which is either a path and file name for a storage file or NULL. If the specifier 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 the specifier ends with a "\" or is NULL, a unique file name will be created. The file name will resemble "SP_7454901D23334AAF87707147726EC235.dat", where "SP_" and ".dat" are the default prefix name and file extension. The numbers in between indicate a generated GUID to ensure that the file name is unique.

    If the file name specifier contains a "%d", it is replaced by a number to give a unique file name. The default file extension is .dat, but 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 for which to retrieve the path. The caller can force creation of a folder by combining the folder CSIDL with CSIDL_FLAG_CREATE. If pszFileNameSpecifier is NULL or "\", nFolder must indicate a specified CSIDL folder combined with CSIDL_FLAG_CREATE to force file creation.

  • ppszFilePath
    [out] Address of a pointer to a null-terminated string specifying file path information. The associated object must be freed when no longer required.

Return Values

The following table shows the possible 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 an object token for a test file.

HRESULT hr;
GUID guid0;
GUID guid1;

CComPtr cpSpObjectToken;
CSpCoTaskMemPtr cpFileName;
CSpCoTaskMemPtr cpFileName2;

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: sapi.h, sapi.idl.
Link Library: Sapilib.lib.

See Also

ISpObjectToken | SAPI Interfaces

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.