Remove INVALID_HANDLE pattern and add comprehensive exception handling documentation

audiodecoder/current/com/rdk/hal/audiodecoder/IAudioDecoder.aidl

@@ -32,6 +32,13 @@ import com.rdk.hal.PropertyValue;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -56,6 +63,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns Capabilities parcelable.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
      */
     Capabilities getCapabilities();
 
@@ -71,6 +80,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid property value.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
+     *
      */
     @nullable PropertyValue getProperty(in Property property);
 
@@ -81,6 +92,8 @@ interface IAudioDecoder
 	 *
      * @exception binder::Status::Exception::EX_NONE for success.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
+     *
      * @see IAudioDecoderListener.onStateChanged().
      */  
     State getState();
@@ -113,6 +126,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      * 
      * @returns IAudioDecoderController or null if the codec or secure is not supported if requested.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
      * 
      * @pre The resource must be in State::CLOSED.
      * 
@@ -139,6 +154,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE If instance is not in OPENED State.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
+     *
      * @see open()
      */
     boolean close(in IAudioDecoderController audioDecoderController);
@@ -158,6 +175,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
+     *
      * @see unregisterEventListener()
      */
     boolean registerEventListener(in IAudioDecoderEventListener audioDecoderEventListener);
@@ -174,6 +193,8 @@ interface IAudioDecoder
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoder}} for exception handling behavior).
+     *
      * @see registerEventListener()
      */
     boolean unregisterEventListener(in IAudioDecoderEventListener audioDecoderEventListener);

audiodecoder/current/com/rdk/hal/audiodecoder/IAudioDecoderController.aidl

@@ -27,6 +27,13 @@ import com.rdk.hal.PropertyValue;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -46,6 +53,8 @@ interface IAudioDecoderController {
      *
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid property and propertyValue.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoderController}} for exception handling behavior).
      */
     boolean setProperty(in Property property, in PropertyValue propertyValue);
 
@@ -102,6 +111,8 @@ interface IAudioDecoderController {
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE 
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoderController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::STARTED.
      */
@@ -179,6 +190,8 @@ interface IAudioDecoderController {
      *
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoderController}} for exception handling behavior).
      *           Thrown if the resource is not in State::STARTED.
      *
      * @pre The decoder resource must be in State::STARTED.

audiodecoder/current/com/rdk/hal/audiodecoder/IAudioDecoderManager.aidl

@@ -24,6 +24,13 @@ import com.rdk.hal.audiodecoder.IAudioDecoder;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -43,6 +50,8 @@ interface IAudioDecoderManager
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns IAudioDecoder.Id[]
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoderManager}} for exception handling behavior).
      */
     IAudioDecoder.Id[] getAudioDecoderIds();
 
@@ -54,6 +63,8 @@ interface IAudioDecoderManager
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns IAudioDecoder which can be null if the resource index is invalid.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioDecoderManager}} for exception handling behavior).
      */
     @nullable IAudioDecoder getAudioDecoder(in IAudioDecoder.Id decoderResourceId);
 }

audiosink/current/com/rdk/hal/audiosink/IAudioSink.aidl

@@ -31,6 +31,13 @@ import com.rdk.hal.State;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -56,6 +63,8 @@ interface IAudioSink
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns Capabilities parcelable.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
      */
     Capabilities getCapabilities();
 
@@ -69,6 +78,8 @@ interface IAudioSink
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid property value.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
+     *
      * @see setProperty()
      */
     @nullable PropertyValue getProperty(in Property property);
@@ -83,6 +94,8 @@ interface IAudioSink
      *
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid parameters.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
      * 
      * @see getProperty()
      */
@@ -94,6 +107,8 @@ interface IAudioSink
      * @returns State enum value.
      *
      * @exception binder::Status::Exception::EX_NONE for success.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
      * 
      * @see IAudioSinkEventListener.onStateChanged().
      */  
@@ -120,6 +135,8 @@ interface IAudioSink
     * @exception binder::Status::Exception::EX_ILLEGAL_STATE If the resource is not in the CLOSED state.
     * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT for invalid parameters.
     * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
     *
     * @pre The resource must be in the CLOSED state.
     *
@@ -146,6 +163,8 @@ interface IAudioSink
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE If instance is not in OPENED State.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.     
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
+     *
      * @see open()
      */
     boolean close(in IAudioSinkController audioSinkController);
@@ -165,6 +184,8 @@ interface IAudioSink
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
+     *
      * @see unregisterEventListener()
      */
     boolean registerEventListener(in IAudioSinkEventListener audioSinkEventListener);
@@ -181,6 +202,8 @@ interface IAudioSink
      * @exception binder::Status::Exception::EX_NONE for success.
      * @exception binder::Status::Exception::EX_NULL_POINTER for Null object.
      *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSink}} for exception handling behavior).
+     *
      * @see registerEventListener()
      */
     boolean unregisterEventListener(in IAudioSinkEventListener audioSinkEventListener);

audiosink/current/com/rdk/hal/audiosink/IAudioSinkController.aidl

@@ -27,6 +27,13 @@ import com.rdk.hal.audiodecoder.FrameMetadata;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -44,6 +51,8 @@ interface IAudioSinkController {
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE
      * 
      * @returns boolean - true on success or false if the ID is invalid or not IAudioDecoder.Id.UNDEFINED.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::READY.
      * 
@@ -58,6 +67,8 @@ interface IAudioSinkController {
      *
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::READY or State::STARTED.
      * 
@@ -118,6 +129,8 @@ interface IAudioSinkController {
     * @exception binder::Status::Exception::EX_NONE for success
     * @exception binder::Status::Exception::EX_ILLEGAL_STATE    If the resource is not in the `STARTED` state or an audio frame is passed after EOS.
     * @exception binder::Status::Exception::EX_ILLEGAL_ARGUMENT If an invalid argument is provided.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
     *
     * @pre The resource must be in the `STARTED` state.
     */
@@ -146,6 +159,8 @@ interface IAudioSinkController {
      * 
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE 
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::READY or State::STARTED.
      */
@@ -160,6 +175,8 @@ interface IAudioSinkController {
      *
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE 
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::READY or State::STARTED.
      */
@@ -186,6 +203,8 @@ interface IAudioSinkController {
      *
      * @exception binder::Status::Exception::EX_NONE for success
      * @exception binder::Status::Exception::EX_ILLEGAL_STATE 
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkController}} for exception handling behavior).
      * 
      * @pre The resource must be in State::STARTED.
      */

audiosink/current/com/rdk/hal/audiosink/IAudioSinkManager.aidl

@@ -25,6 +25,13 @@ import com.rdk.hal.audiosink.PlatformCapabilities;
  *  @author    Luc Kennedy-Lamb
  *  @author    Peter Stieglitz
  *  @author    Douglas Adler
+ *
+ *  <h3>Exception Handling</h3>
+ *  Unless otherwise specified, this interface follows standard Android Binder semantics:
+ *  - <b>Success</b>: The method returns `binder::Status::Exception::EX_NONE` and all output parameters/return values are valid.
+ *  - <b>Failure (Exception)</b>: The method returns a service-specific exception (e.g., `EX_SERVICE_SPECIFIC`, `EX_ILLEGAL_ARGUMENT`).
+ *    In this case, output parameters and return values contain undefined (garbage) memory and must not be used.
+ *    The caller must ignore any output variables.
  */
 
 @VintfStability
@@ -39,6 +46,8 @@ interface IAudioSinkManager
      * @returns IAudioSink.Id[] array.
      *
      * @exception binder::Status::Exception::EX_NONE for success.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkManager}} for exception handling behavior).
      */
 	IAudioSink.Id[] getAudioSinkIds();   
 
@@ -52,6 +61,8 @@ interface IAudioSinkManager
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns PlatformCapabilities parcelable.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkManager}} for exception handling behavior).
      */
     PlatformCapabilities getPlatformCapabilities();
 
@@ -63,6 +74,8 @@ interface IAudioSinkManager
      * @exception binder::Status::Exception::EX_NONE for success.
      *
      * @returns IAudioSink or null on invalid audio sink ID.
+     *
+     * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IAudioSinkManager}} for exception handling behavior).
      */
     @nullable IAudioSink getAudioSink(in IAudioSink.Id audioSinkId);