Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

This function sets the current sound file for the indicated event.

Syntax 

HRESULT SndSetSound (
   SND_EVENT 
seSoundEvent,
   const SNDFILEINFO* 
pSoundFileInfo,
   BOOL 
fSuppressUI
);

Parameters

seSoundEvent

[in] Indicates which type of sound event the user wishes to set.

pSoundFileInfo

[in] A pointer to a SNDFILEINFOstructure which indicates the file that the user wishes to set as the indicated sound. The fully qualified path should be included. szDisplayNamemember of SNDFILEINFOis ignored.

fSuppressUI

[in] Determines if error message should be displayed if the function fails to set the current sound file. This error message would only appear in the case of failure.

Return Value

The function may return any HRESULT and the application should use the SUCCEEDED and FAILED macros to check the results.

Remarks

This function sets the current sound file for the appropriate event. This function can fail and will not change the current sound file if it determines it is unable to play the sound file for any reason. It will also fail if the sound file is not in an appropriate sounds directory. It will fail if a sound file is in the ROM sounds directory, unless it is returned by SndGetSoundFileList. If fSuppressUIis true, no user interface will be displayed explaining reasons that the sound file could not be set. If it is false, then a dialog may appear explaining the reason the sound file could not be set such as insufficient digital rights, an invalid file, etc.

Note:
The SND_EVENT_ALL event type and corresponding SND_SOUNDTYPE values are currently only supported on Windows Mobile Professional and Windows Mobile Classic.

Code Example

The following code example demonstrates how to use SndSetSound.

Note:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
Copy Code 
void CopyAndSetRingtone(TCHAR* pszCurrentDirectory, TCHAR*
pszFileName)
{
	TCHAR szPathAndFile[MAX_PATH];
	TCHAR szDestination[MAX_PATH];
	// Initialize an empty SNDFILEINFO structure.
	SNDFILEINFO sndFile			 = {0};
	SNDDIRECTORYINFO* pSndDirectories = NULL;
	int cSoundDirectories			 = 0;
	// Build the path to the file.
	StringCchPrintf(szPathAndFile, MAX_PATH, _T("%s\\%s"),
pszCurrentDirectory, pszFileName);
	// Get the list of User Data directories.
	SndGetSoundDirectoriesList(SND_EVENT_RINGTONELINE1,
SND_LOCATION_USERDATA, &pSndDirectories,
&cSoundDirectories);
	// Set the destination to the first User Data directory.
	StringCchPrintf(szDestination, MAX_PATH, _T("%s\\%s"),
pSndDirectories->szPathName, pszFileName);
	CopyFile(szPathAndFile, szDestination, FALSE);
	// Setup values in the SNDFILEINFO structure.
 only need to set sndFile.szPathName, not sndFile.szDisplayName.
	sndFile.sstType = SND_SOUNDTYPE_FILE;
	StringCchCopy(sndFile.szPathName, MAX_PATH, szDestination);
	// Set the ringtone.
	SndSetSound(SND_EVENT_RINGTONELINE1, &sndFile, TRUE);
	// Free memory.
	LocalFree(pSndDirectories);
	return;
}

Requirements

Header soundfile.h
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also

Concepts

Sounds Reference