Clarifications and improvements needed for HDMI-CEC API behavior and documentation

[bhanucbp]

I’d like to start a discussion regarding certain ambiguities and inconsistencies observed in the HDMI-CEC module’s API design and documentation. Below are the key points for review and clarification:

1. Property enum value types

• The Property enum entries don’t specify the type of value they return (e.g., int, long int, etc.).
• Suggestion: Add explicit type information in the documentation or API definition for each property.

2. Incorrect description of onMessageReceived callback

• The documentation for the onMessageReceived() callback in the event listener is not correct.
• Requesting clarification and update to reflect the correct behaviour.

3. Behavior when addLogicalAddresses() is not called before sendMessage()

If a client doesn't call addLogicalAddresses() and then sendMessage(), what should be the expected behaviour?

• Does the API simply send the message?
• Or does it return an error if logical addresses are not yet configured/validated?

4. Redundancy of onMessageSent in controller listener (IHdmiCecControllerListener)

• The client invoking sendMessage() already receives a return value indicating success/failure.
• Why do we also need an onMessageSent() callback in the controller listener?
• It seems more useful in the event listener (IHdmiCecEventListener), since a third-party client (e.g., a diagnostic tool) won’t have access to the return value of sendMessage().
• Proposal: Move or add onMessageSent() to the event listener for broader usability.

5. Broadcast message handling

The SendMessageStatus defines:

/**
     * Directly Addressed Message: The message was sucessfully acknowledged by the directly addressed follower.
     * Broadcast Message: One or more devices rejected the message.
     *                    At least one retransmission was attempted.
     */
    ACK_STATE_0 = 0, 

• For broadcast messages, the sender does not know if any device rejects, ignores, or fails to respond. CEC is a one-way broadcast
• Hence, there is no retransmission expected.
• Need confirmation that this is the intended design behaviour.

[Ulrond]

Hi @bhanucbp,

Reviewing these against the current develop branch:

1. Property types — Resolved. All CEC properties now have explicit type and access annotations in Property.aidl.
2. onMessageReceived description — Could you clarify what specifically is incorrect? The current documentation describes the CEC frame format and EOM/ACK bit handling. Without specifics we can't action this.
3. sendMessage without addLogicalAddresses — sendMessage() transmits regardless. addLogicalAddresses() controls the receive filter, not the send path. No change needed.
4. onMessageSent placement — Already on IHdmiCecEventListener for diagnostic/observer use. The controller gets the synchronous SendMessageStatus return.
5. Broadcast ACK semantics — Correct per HDMI 1.4b CEC 6.1.2. The inverted ACK sense for broadcast is by specification.

Closing as resolved. Please reopen or file a new issue if point 2 needs further attention.