#include <twl/snd.h>SNDEXResult SNDEX_SetVolumeAsync( u8 volume, SNDEXCallback callback, void* arg );| volume | Speaker volume. You can specify any value between 0 (defined as SNDEX_VOLUME_MIN) and 7 (defined as SNDEX_VOLUME_MAX). |
|---|---|
| callback | SNDEXCallback-type function that will be notified when the asynchronous process has completed. The asynchronous process will run even if NULL is specified here, but you will no longer be able to detect that it has completed. |
| arg | Argument to pass to the function specified in callback. |
SNDEX_RESULT_SUCCESS |
Asynchronous processing started successfully. The asynchronous processing results will be passed as an argument to the function registered in callback. |
|---|---|
SNDEX_RESULT_ILLEGAL_STATE |
This function has been called on the NITRO platform. |
SNDEX_RESULT_INVALID_PARAM |
A value outside of the specifiable range is given for volume. |
SNDEX_RESULT_BEFORE_INIT |
Extended sound features have not been initialized by the SNDEX_Init function. |
SNDEX_RESULT_EXCLUSIVE |
Processing for other extended sound features is running. Note that mutexes are used for each of the extended sound features, so they cannot be used simultaneously. As mentioned in the SNDEX Library Overview, the error also returns during processing of shutter sound playback. |
SNDEX_RESULT_PXI_SEND_ERROR |
A PXI command failed to be sent to the ARM7. This error occurs when the PXI send queue for the ARM7 has filled up or when the hardware has detected an error. As a result, the state may improve when a retry is made. |
SNDEX_RESULT_SUCCESS |
The whole series of operations completed successfully. |
|---|---|
SNDEX_RESULT_EXCLUSIVE |
A mutex error occurred in the ARM7. This error depends upon the progress of ARM7 processing, so conditions may improve when a retry is made. |
SNDEX_RESULT_DEVICE_ERROR |
The ARM7 internally failed to change the speaker volume for an external device. Conditions may improve on a retry, but continued failures after multiple retries could indicate that the external device is not responding, so you may handle this as if it were a notification of success. |
SNDEX_RESULT_FATAL_ERROR |
This error should not ordinarily occur. This may occur when an illegal PXI command was sent directly, ignoring library state management; when the ARM7 component and the extended sound feature library have different versions; when library state management has fallen into an abnormal state due to memory corruption; or when other such conditions arise. There is no way to recover from this at run time. |
Asynchronously changes the speaker volume. The changes are not necessarily applied immediately. For more information, see Note, below.
In addition to this function, the SNDEX_SetVolume function and the console's volume switch can be used to change the speaker volume. The console will record the changed value and will also apply it at the next restart.
If this function does not return a value of SNDEX_RESULT_SUCCESS, the asynchronous processing and callback will not be run. Also note that a PXI receive interrupt will send notification when the asynchronous processing is complete, so callbacks will not occur if PXI receive interrupts are prohibited.
Be sure that your method for changing the volume adheres to the Programming Guidelines.
The speaker volume is saved in dedicated nonvolatile memory each time it is changed. It consequently cannot be modified an infinite number of times.Avoid frequent changes to the speaker volume from the program.
The library controls the execution of this function to control the number times the volume is changed.
If the function is called during the roughly 10 frames (approximately 167 ms) since the volume was last changed, the new value is not immediately applied but instead held pending. Even if this is the case, the function returns SNDEX_RESULT_SUCCESS.
When the storage time for this pending change has ended, the speaker volume is changed to the value specified in the argument of the last-called SNDEX_SetVolume[Async] function.
The value returned by the SNDEX_GetVolume[Async] function is the pending change to the speaker volume. If no value is pending, the currently set speaker volume is returned.
The callback function specified in the argument of this function is called when the function process ends, not when the change to speaker volume is actually applied.
SNDEX_SetVolume
SNDEX_GetVolumeAsync
2009/02/03 Added mention of the Programming Guidelines in Note.
2009/01/06 Added mention of library control over changes in speaker volume, and added definitions for minimum and maximum speaker volume.
2008/11/07 Added mention that SNDEX_RESULT_EXCLUSIVE is returned during shutter sound playback.
2008/11/06 Made correction to Asynchronous Process Results (SNDEX_RESULT_EXCLUSIVE) in Return Values.
2008/07/10 Revised the explanation about speaker volume.
2008/02/22 Standardized terminology regarding speaker volume and added Description.
2008/02/15 Initial version.
CONFIDENTIAL