SndSetSound

Article
11/18/2015

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 SNDFILEINFO structure which indicates the file that the user wishes to set as the indicated sound. The fully qualified path should be included. szDisplayName member of SNDFILEINFO is 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 fSuppressUI is 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.

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

Partager via