[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSRadioTuner Object

The UMSRadioTuner is a device specific object that controls an FM radio tuner. The tuner tunes stations between 88100 MHz and 107900 MHz. Stations are tuned in 200 MHz increments. This object is an interface to the tuner hardware. It will select a station, scan for string stations, return the status (tuned, stereo) of a station, and mute/unmute the audio. The actual volume of the audio is controlled through the master volume applet.

The RadioTuner hardware connects to the AUX1 input. This input must be active in order to hear the radio. AUX1 can be activated via master_settings at runtime. AUX1 is the same input as the CDROM. The CD audio is mixed with the radio audio.

You must call the open method to start tuning radio stations.

To learn more about the UMSRadioTuner object, see:

For introductory information, see Tuner Objects.

Method Descriptions

ReturnCode open (in string path)

Description

This method opens the Radio Tuner interface on the tuner device driver. This method must be called before other methods will work. After the interface is opened, the object will attempt to tune the default frequency (88100 KHz).

Arguments
in string path Pointer to the driver (for example, /dev/svc0). Because there may be multiple cards or the card might have been moved, the object relies on the caller to pass this information. The radio channel is appended to the path by the open method.
Return Values
Success Call completed successfully.
InvalidArgument Path was incorrect.
DeviceError Call to driver failed. errno is set.

ReturnCode close()

Description

This method closes the device driver.

Return Values
Success Call completed successfully.
DeviceError Method call to driver failed. errno is set.

ReturnCode select_channel(in long channel, out long status)

Description

This method allows the caller to set the Radio Tuner to a specific frequency. The frequency is designated in kilohertz (for example, 93.7 FM is 93700). The valid frequency range is 88100 to 107900. This method returns the status, which is a combination of whether the frequency is tuned and whether it is stereo or mono.

Arguments
in long channel The radio frequency in kilohertz.
out long status The enumerated type tuner_status and the status of the frequency. Possible status states are NotTuned, TunedMono, and TunedStereo.
Return Values
Success Call completed successfully.
DeviceNotOpen Call to open was never made (or failed).
DeviceError Call to driver failed. errno is set.
NullPointer The status out parameter was not allocated properly.
InvalidArgument Frequency was not in the correct range.

ReturnCode get_current_channel( out long channel, out boolean Tuned)

Description

This method returns the current channel and indicates whether the frequency is tuned.

Arguments
out long channel The frequency is in kilohertz. The default channel is 88100 KHz.
out boolean Tuned A value of True if the current station is in tune.
Return Values
Success Call completed successfully.
DeviceNotOpen Call to open was never made (or failed).
DeviceError Call to driver failed. errno is set.
NullPointer The out parameters were not allocated properly.
NotCompleteTryAgain The previous operation was a seek without blocking and the driver was not finished seeking when the call to get the status was made.

ReturnCode next_channel(in UMSTuner_Direction direction, out long status)

Description

This method increment or decrement the radio frequency by 200 KHz. The direction is set via the direction argument. The status feature is the same as that of the select_channel method.

Arguments
in UMSTuner_Direction direction The direction to increment or decrement, either Up or Down.
out long status The enumerated type tuner_status.
Return Values
Success Call completed successfully.
DeviceNotOpen Call to open was never made (or failed).
DeviceError Call to driver failed. errno is set.
NullPointer The status parameter was not allocated properly.

ReturnCode seek_to_next_avail_channel( in long locking_strength, in UMSTuner_Direction direction, in boolean block)

Description

This method scans to the next radio station. The direction of the scan (up or down) is determined by the direction argument. The locking strength is an integer between 0 and 3 that tells the tuner whether to stop on a frequency and call it tuned. A locking strength of 0 is Very Low and a strength of 3 is Very High. This call should be followed by a get_current_channel call to see where the tuner stopped and what status is (tuned, stereo, etc.). If the call is blocked, it does not return until the seek is complete. If no channels are tuned, the object resets the tuner to the default channel of 88100 KHz.

Arguments
in long locking_strength An integer between 0 and 3 used as criteria for the tuner when it is tuning frequencies.
in UMSTuner_Direction direction The direction to increment or decrement, either Up or Down.
in boolean block An indication of whether to block.
Return Values
Success Call completed successfully.
DeviceNotOpen Call to open was never made (or failed).
DeviceError Call to driver failed. errno is set.

ReturnCode set_mute(in UMSTuner_OnOff mute)

Description

This method sets and resets the mute on the radio.

Arguments
in UMSTuner_OnOff mute Turns the mute On or Off.
Return Values
Success Call completed successfully.
DeviceNotOpen Call to open was never made (or failed).
DeviceError Call to driver failed. errno is set.

ReturnCode get_mute(out UMSTuner_OnOff mute)

Description

This methods returns the current mute state.

Arguments
out UMSTuner_OnOff mute The current mute state. The default value is Off.
Return Values
Success Call completed successfully.
NullPointer The out parameter mute was not allocated properly.

ReturnCode set_stereo_audio( in UMSTuner_OnOff stereo)

Description

This method sets whether stereo or mono is requested. This might not be what is actually tuned, but it is used for the request to the hardware.

Arguments
in UMSTuner_OnOff stereo Turns the stereo On or Off. The default value is On.
Return Values
Success Call completed successfully.

ReturnCode get_stereo_audio(out UMSTuner_OnOff stereo)

Description

This method returns the current stereo state. If you request stereo by using the set_stereo_audio call and the tuner is tuned to a mono station, the value of Off is returned on this call.

Arguments
out UMSTuner_OnOff stereo Returns the state of the stereo as On or Off.
Return Values
Success Call completed successfully.
NullPointer The out parameter was not allocated properly.

ReturnCode set_timeout_value(in long timeout_ms)

Description

This method sets a timeout value for use by the select_channel method. This value is the maximum time, in milliseconds (ms), that the driver waits on a PRESET call for the station to be tuned.

Arguments
in long timeout_ms The timeout value in milliseconds that the select_channel method uses.
Return Values
Success Call completed successfully.
InvalidArgument The timeout value was not reasonable (negative or > 60 seconds).

ReturnCode get_timeout_value(out long timeout_ms)

Description

This method returns the user-defined timeout value or the default value if the timeout value has not been set.

Arguments
out long timeout_ms The timeout value in milliseconds that the select_channel method uses.
Return Values
Success Call completed successfully.
NullPointer The out parameter was not allocated properly.

For introductory information, see Tuner Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]