# PMi_SetSoundVolume*

## C Specification

      #include <nitro/spi.h>

      u32 PMi_SetSoundVolume( PMSoundVolumeSwitch sw );

      u32 PMi_SetSoundVolumeAsync( PMSoundVolumeSwitch sw,
      PMCallback callback,
      void* arg );

## Arguments

sw | The effective switch of sound external volume.
callback | The callback that is called when the command finishes.
arg | The argument that is used when calling the callback.

## Return Values

The `PM_RESULT_SUCCESS` return value indicates that that the execution of the command has succeeded (for synchronous functions) or that the command was successfully sent to the ARM7 processor (for asynchronous functions). The `PM_INVALID_COMMAND` return value indicates that the argument that was passed is invalid. The `PM_RESULT_ERROR` return value indicates that an error has occurred with the ARM7 processor.

## Description

This function switches the effective switch of external sound volume.
The `sw` argument is a `PMSoundVolumeSwitch` enumerator type that can contain either one of the following values:

`PM_SOUND_VOLUME_OFF` | Turns off the external sound volume and forces the speaker output at maximum volume.
`PM_SOUND_VOLUME_ON` | Turns on the external sound volume.

This function uses PXI to send the command that performs the corresponding operation in the ARM7 processor. The ARM7 side that receives that command is executed by operating the PMIC. Therefore, this function may not operate promptly after you call it. A synchronous function that waits for the operation to finish, as well as an asynchronous function that only sends command to ARM7, are provided. Use either of the functions depending on your operational requirements. (The asynchronous function has "Async" as part of the function name.))

When an asynchronous function is called, the specified `callback` is called when processing on the ARM7 side finishes. The callback type `PMCallback` is defined by:

> ``typedef void ( *PMCallback )( u32 result, void* arg )`;`

This callback is called from within the PXI interrupt handler.

The `result` argument is the first argument in the callback. The `result` argument shows the results of the command as either `PM_RESULT_SUCCESS` or `PM_RESULT_ERROR`. The second argument in the callback returns the value `arg`.

Before you use this function, initialize the PM library by using the `PM_Init()` function. The `PM_Init()` function has to be called only once. Also, when you call `OS_Init()`, there is no need to call `PM_Init()` separately since it is called from within `OS_Init()`.)

## Internal Operation

Operates the PMIC_CTL of the PMIC register.

## See Also

`PM_Init`, `PMi_SetSoundPower*`

## Revision History

06/02/2005 Clarified the location from which the callback is called.
08/09/2004 Moved from PM to PMi.
07/31/2004 Initial version.

CONFIDENTIAL