Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[AudioManager] Improve documentation #6352

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[AudioManager] Improve documentation #6352

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 68 additions & 19 deletions src/Tizen.Multimedia/AudioManager/AudioDevice.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,11 @@
namespace Tizen.Multimedia
{
/// <summary>
/// Provides the ability to query the information of sound devices.
/// Represents an audio device in the system, providing functionality to query and manipulate its properties.
/// The <see cref="AudioDevice"/> class allows developers to interact with audio devices by retrieving
/// detailed information such as the device's ID, name, type, I/O direction, and its current running state.
/// Furthermore, it provides methods for getting and setting sample formats and rates, managing resampling options,
/// and restricting stream types to media-only, facilitating optimized audio handling for diverse applications.
/// </summary>
/// <since_tizen> 3 </since_tizen>
public class AudioDevice
Expand Down Expand Up @@ -51,35 +55,47 @@ internal AudioDevice(IntPtr deviceHandle)
}

/// <summary>
/// Gets the ID of the device.
/// Gets the unique identifier of the audio device.
/// This ID serves as a reference to identify the device within the system and
/// is crucial for performing operations on specific devices.
/// </summary>
/// <value>The id of the device.</value>
/// <since_tizen> 3 </since_tizen>
public int Id => _id;

/// <summary>
/// Gets the name of the device.
/// Gets the name of the audio device.
/// This property provides a human-readable identifier for the device,
/// which can be used in user interfaces or logs to display information
/// about the current audio output/input device.
/// </summary>
/// <value>The name of the device.</value>
/// <since_tizen> 3 </since_tizen>
public string Name { get; }

/// <summary>
/// Gets the type of the device.
/// Gets the type of the audio device.
/// This property returns an enumerated value of type <see cref="AudioDeviceType"/>
/// that indicates the specific category of the device, such as speakers, microphones,
/// or headphones, which helps in distinguishing between different device functionalities.
/// </summary>
/// <value>The <see cref="AudioDeviceType"/> of the device.</value>
/// <since_tizen> 3 </since_tizen>
public AudioDeviceType Type => _type;

/// <summary>
/// Gets the IO direction of the device.
/// Gets the input/output (I/O) direction of the audio device.
/// This property indicates whether the device is designed for input (recording) or output (playback),
/// allowing developers to manage device usage appropriately in their applications.
/// </summary>
/// <value>The IO direction of the device.</value>
/// <since_tizen> 3 </since_tizen>
public AudioDeviceIoDirection IoDirection => _ioDirection;

/// <summary>
/// Gets the running state of the device.
/// Gets a value indicating whether the audio device is currently running.
/// This property checks the operational state of the device and returns <c>true</c>
/// if the device is active and processing audio, or <c>false</c> if it is idle or inactive.
/// </summary>
/// <value>true if the audio stream of device is running actually; otherwise, false.</value>
/// <since_tizen> 5 </since_tizen>
Expand All @@ -95,7 +111,10 @@ public bool IsRunning
}

/// <summary>
/// Gets the device's supported sample formats.
/// Retrieves a collection of audio sample formats supported by the device.
/// This method returns an enumerable list of <see cref="AudioSampleFormat"/> values
/// indicating the different audio formats the device can handle, enabling applications
/// to select a compatible format for audio processing.
/// </summary>
/// <returns>An IEnumerable&lt;AudioSampleFormat&gt; that contains supported sample formats.</returns>
/// <remarks>
Expand Down Expand Up @@ -127,7 +146,9 @@ IEnumerable<AudioSampleFormat> RetrieveFormats()
}

/// <summary>
/// Sets the device's sample format.
/// Sets the sample format for the audio device.
/// This method allows developers to specify a desired <see cref="AudioSampleFormat"/> for
/// audio playback or recording.
/// </summary>
/// <param name="format">The <see cref="AudioSampleFormat"/> to set to the device.</param>
/// <remarks>
Expand All @@ -142,7 +163,9 @@ public void SetSampleFormat(AudioSampleFormat format)
}

/// <summary>
/// Gets the device's sample format.
/// Gets the current sample format used by the audio device.
/// This method retrieves the current <see cref="AudioSampleFormat"/> the device is operating with,
/// allowing applications to verify or adjust to the active format being utilized for audio streams.
/// </summary>
/// <returns>The <see cref="AudioSampleFormat"/> of the device.</returns>
/// <remarks>
Expand Down Expand Up @@ -195,7 +218,9 @@ private uint ConvertRateToCoreValue(uint rate)
}

/// <summary>
/// Gets the device's supported sample rates.
/// Retrieves the sample rates that the audio device supports.
/// This method returns an enumerable list of supported sample rates, allowing developers
/// to select an appropriate rate for audio processing based on the capabilities of the device.
/// </summary>
/// <returns>An IEnumerable&lt;uint&gt; that contains supported sample rates.</returns>
/// <remarks>
Expand Down Expand Up @@ -229,7 +254,10 @@ IEnumerable<uint> RetrieveRates()
}

/// <summary>
/// Sets the device's sample rate.
/// Sets the sample rate for the audio device.
/// This method allows you to specify a desired sample rate (in Hz) for audio playback or recording.
/// Choosing an appropriate sample rate is important for maintaining audio quality and ensuring compatibility
/// with audio data formats.
/// </summary>
/// <param name="rate">The sample rate to set to the device.</param>
/// <remarks>
Expand All @@ -244,7 +272,9 @@ public void SetSampleRate(uint rate)
}

/// <summary>
/// Gets the device's sample rate.
/// Gets the current sample rate of the audio device.
/// This method retrieves the sample rate currently in use for audio processing, allowing
/// applications to ensure they are operating with the correct audio quality settings.
/// </summary>
/// <returns>The sample rate of the device.</returns>
/// <remarks>
Expand All @@ -261,7 +291,10 @@ public uint GetSampleRate()
}

/// <summary>
/// Sets the device's 'avoid resampling' property.
/// Sets the 'avoid resampling' property for the audio device.
/// This property controls whether the device should avoid resampling audio data during playback.
/// Enabling this feature can help preserve audio quality by preventing alterations to audio that
/// may happen during playback.
/// </summary>
/// <param name="enable">The 'avoid resampling' value to set to the device.</param>
/// <remarks>
Expand All @@ -279,7 +312,9 @@ public void SetAvoidResampling(bool enable)
}

/// <summary>
/// Gets the device's 'avoid resampling' property.
/// Gets the current state of the 'avoid resampling' property for the audio device.
/// This method returns whether the device is currently configured to avoid resampling audio data,
/// allowing developers to assess the current settings related to audio processing quality.
/// </summary>
/// <returns>The 'avoid resampling' property of the device.</returns>
/// <remarks>
Expand All @@ -298,7 +333,10 @@ public bool GetAvoidResampling()
}

/// <summary>
/// Sets the restriction of stream type only for media.
/// Sets a restriction on the audio device to allow only media streams.
/// This method configures the device to accept only audio streams of type
/// <see cref="AudioStreamType.Media"/>. When enabled, the device will reject
/// any other stream types, ensuring that it is exclusively used for media playback.
/// </summary>
/// <param name="enable">The 'media stream only' value to set to the device.</param>
/// <remarks>
Expand All @@ -315,7 +353,9 @@ public void SetMediaStreamOnly(bool enable)
}

/// <summary>
/// Gets the restriction of stream type only for media.
/// Retrieves the current restriction status of the audio device regarding media streams.
/// This method checks whether the device is currently configured to accept only media streams,
/// returning a boolean value that indicates the state of the restriction.
/// </summary>
/// <returns>The 'media stream only' property of the device.</returns>
/// <remarks>
Expand All @@ -334,15 +374,21 @@ public bool GetMediaStreamOnly()
}

/// <summary>
/// Returns a string that represents the current object.
/// Returns a string representation of the current instance.
/// This method provides a formatted string that includes key properties of the audio device,
/// such as its unique identifier, name, type, I/O direction, and running state.
/// This representation can be useful for logging, debugging, or displaying device information
/// in user interfaces.
/// </summary>
/// <returns>A string that represents the current object.</returns>
/// <since_tizen> 4 </since_tizen>
public override string ToString() =>
$"Id={Id}, Name={Name}, Type={Type}, IoDirection={IoDirection}, IsRunning={IsRunning}";

/// <summary>
/// Compares an object to an instance of <see cref="AudioDevice"/> for equality.
/// Compares the current instance of <see cref="AudioDevice"/> with another object for equality.
/// This method checks if the specified object is an instance of <see cref="AudioDevice"/>
/// and compares their unique identifiers to determine if they represent the same audio device.
/// </summary>
/// <param name="obj">A <see cref="Object"/> to compare.</param>
/// <returns>true if the two devices are equal; otherwise, false.</returns>
Expand All @@ -359,7 +405,10 @@ public override bool Equals(object obj)
}

/// <summary>
/// Gets the hash code for this instance of <see cref="AudioDevice"/>.
/// Retrieves the hash code for the current instance of <see cref="AudioDevice"/>.
/// This method generates a hash code based on the unique identifier of the audio device,
/// which can be useful for storing instances in hash-based collections such as dictionaries
/// or hash sets.
/// </summary>
/// <returns>The hash code for this instance of <see cref="AudioDevice"/>.</returns>
/// <since_tizen> 4 </since_tizen>
Expand Down
19 changes: 17 additions & 2 deletions src/Tizen.Multimedia/AudioManager/AudioDeviceConnectionChangedEventArgs.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ namespace Tizen.Multimedia
{
/// <summary>
/// Provides data for the <see cref="AudioManager.DeviceConnectionChanged"/> event.
/// This event is triggered when there is a change in the connection status of an audio device,
/// such as when a device is connected or disconnected from the system.
/// The <see cref="AudioDeviceConnectionChangedEventArgs"/> class encapsulates information
/// about the device involved in the connection change and its current connection state,
/// allowing developers to easily respond to changes in the audio subsystem and update
/// application behavior accordingly.
/// </summary>
/// <since_tizen> 3 </since_tizen>
public class AudioDeviceConnectionChangedEventArgs : EventArgs
Expand All @@ -31,14 +37,23 @@ internal AudioDeviceConnectionChangedEventArgs(AudioDevice device, bool isConnec
}

/// <summary>
/// Gets the device.
/// Gets the device that is involved in the connection change.
/// This property returns an instance of <see cref="AudioDevice"/>, which represents
/// the specific audio device that has been connected or disconnected.
/// This information is essential for applications that need to manage multiple audio devices,
/// allowing them to identify the affected device and adjust their functionality accordingly.
/// </summary>
/// <value>The <see cref="AudioDevice"/>.</value>
/// <since_tizen> 3 </since_tizen>
public AudioDevice Device { get; }

/// <summary>
/// Gets the connection state of the device.
/// Gets the current connection state of the device.
/// This property indicates whether the audio device is currently connected to the system.
/// It will return <c>true</c> if the device is connected and <c>false</c> if it has
/// been disconnected. This information is crucial for determining the audio routing and
/// playback options, enabling applications to appropriately react to the presence
/// or absence of audio devices in the environment.
/// </summary>
/// <value>true if the device is connected; otherwise, false.</value>
/// <since_tizen> 3 </since_tizen>
Expand Down
4 changes: 3 additions & 1 deletion src/Tizen.Multimedia/AudioManager/AudioDeviceIoDirection.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@
namespace Tizen.Multimedia
{
/// <summary>
/// Specifies the audio device directions.
/// Defines the data flow directions for audio devices, indicating whether
/// a device is for input, output, or both. This helps in managing audio
/// interactions within applications effectively.
/// </summary>
/// <since_tizen> 3 </since_tizen>
public enum AudioDeviceIoDirection
Expand Down
8 changes: 6 additions & 2 deletions src/Tizen.Multimedia/AudioManager/AudioDeviceRunningChangedEventArgs.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,11 @@
namespace Tizen.Multimedia
{
/// <summary>
/// Provides data for the <see cref="AudioManager.DeviceRunningChanged"/> event.
/// Provides the data for the <see cref="AudioManager.DeviceRunningChanged"/> event,
/// which is triggered when the running state of an audio device changes.
/// This class encapsulates information about the specific audio device
/// that has undergone a state change, as well as its current running status,
/// allowing subscribers to respond appropriately to changes in audio device activity.
/// </summary>
/// <since_tizen> 5 </since_tizen>
public class AudioDeviceRunningChangedEventArgs : EventArgs
Expand All @@ -44,4 +48,4 @@ internal AudioDeviceRunningChangedEventArgs(AudioDevice device, bool isRunning)
/// <since_tizen> 5 </since_tizen>
public bool IsRunning { get; }
}
}
}
39 changes: 28 additions & 11 deletions src/Tizen.Multimedia/AudioManager/AudioDeviceType.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,58 +17,75 @@
namespace Tizen.Multimedia
{
/// <summary>
/// Specifies the audio device types.
/// Represents the various types of audio devices available in the system.
/// This enumeration categorizes audio devices based on their functionality and
/// connection type, enabling developers to easily identify and utilize
/// the appropriate audio device for their applications. The types include
/// built-in speakers and microphones, external connections like audio jacks,
/// Bluetooth, HDMI, USB audio, and network audio devices, facilitating
/// effective audio management in diverse scenarios.
/// </summary>
/// <since_tizen> 3 </since_tizen>
public enum AudioDeviceType
{
/// <summary>
/// Built-in speaker.
/// Represents the built-in speaker of the device, typically used for
/// playback of audio through the device's internal audio output.
/// </summary>
BuiltinSpeaker,

/// <summary>
/// Built-in receiver.
/// Represents the built-in receiver, usually utilized for phone calls
/// and communication through the device, providing audio input and output.
/// </summary>
BuiltinReceiver,

/// <summary>
/// Built-in microphone.
/// Represents the built-in microphone, used for capturing audio input
/// from the environment, such as for voice commands, calls, or recordings.
/// </summary>
BuiltinMic,

/// <summary>
/// Audio jack that can be connected to wired accessories such as headphones and headsets.
/// Indicates an audio jack that allows the connection of wired accessories
/// such as headphones and headsets, providing a physical interface for
/// audio playback and recording.
/// </summary>
AudioJack,

/// <summary>
/// Bluetooth media (A2DP).
/// Represents Bluetooth media devices using the A2DP (Advanced Audio
/// Distribution Profile) standard for streaming high-quality audio wirelessly.
/// </summary>
BluetoothMedia,

/// <summary>
/// HDMI.
/// Represents HDMI audio output, allowing the transmission of high-fidelity
/// audio and video to external displays or audio receivers through an HDMI cable.
/// </summary>
Hdmi,

/// <summary>
/// Device for forwarding.
/// Represents devices used for forwarding audio data, which may involve
/// relaying audio signals to other devices or systems for processing or playback.
/// </summary>
Forwarding,

/// <summary>
/// USB audio.
/// Represents USB audio devices, which connect through USB ports to provide
/// audio input and output, such as external sound cards or USB microphones.
/// </summary>
UsbAudio,

/// <summary>
/// Bluetooth voice (SCO).
/// Represents Bluetooth voice devices using the SCO (Synchronous Connection
/// Oriented) profile, primarily used for voice communication over Bluetooth.
/// </summary>
BluetoothVoice,

/// <summary>
/// Device for the transmission of audio data over a network
/// Represents devices that transmit audio data over a network, enabling audio
/// streaming or communication over internet or local networks.
/// </summary>
Network
}
Expand Down
Loading
Loading