IMessagingModule

​

Interface IMessagingModule

interface IMessagingModule

Extends com.amazon.apmf.IStandard Entry-point factory for the messaging package. Provides factory methods for constructing message builders, filters, and property builders, and exposes send, subscribe, and ACL operations. Obtain an instance via Process::getComponent("/com.amazon.kepler.messaging") .QueryInterface<IMessagingModule>().

​

Methods

​

makeMessageBuilder()

IMessageBuilder* makeMessageBuilder(string targetUri)

Makes a new Message builder, which can be used to construct a message for a specific destination. Note that the builder may be reused to construct multiple messages.

​

Parameters

targetUri

string — Required Destination URI of the target(s) of the message. Common schemes:

• unicast://<name> - singleton named target; the system selects a single recipient based on registered filters and manifest entries.
• broadcast://<name> - fan-out delivery to every listener whose filter matches; broadcasts do not support responses.
• Component schemes (e.g. home://, event://) - domain-specific URIs handled by lifecycle entry-point components declared in manifests. Custom-scheme ACL applies; event:// additionally gates access via checkEventUriAccess.

URIs are RFC 3986 compliant. The <name> segment for unicast:// and broadcast:// schemes follows the unreserved-character set (alphanumeric and -, ., _, ~). Query parameters and fragments are accepted in the input but are stripped before filter matching (see IMessageFilterBuilder::baseUri()). Filter matching uses the URI without query parameters or fragments (the “base URI”). See IMessageFilterBuilder::baseUri().

​

Returns

IMessageBuilder* The IMessageBuilder instance that can create messages destined to the target.

​

Throws

• com.amazon.apmf.InvalidArgumentError — if targetUri is malformed or uses an unrecognized scheme.

---

​

makeMessagePropertiesBuilder()

IMessagePropertiesBuilder* makeMessagePropertiesBuilder()

Makes a new Message Properties builder, which can be used to describe IMessageProperties associated with an IMessage. Note that the builder may be reused to construct multiple properties.

​

Returns

IMessagePropertiesBuilder* The IMessagePropertiesBuilder instance that can be used to construct Message Properties.

---

​

makeMessageFilterBuilder()

IMessageFilterBuilder* makeMessageFilterBuilder()

Makes a new Message Filter builder, which can be used to build Message Filters. Filters allow the caller to express interest in messages at runtime. Note that the builder may be reused to construct multiple filters.

​

Returns

IMessageFilterBuilder* The IMessageFilterBuilder instance that can be used to construct Message Filters.

---

​

send()

void send(IMessage* message, IMessageListener? listener)

Sends a message to one or more targets. Responses are delivered to the supplied listener if:

1. the message is not a broadcast. Broadcasts do not support responses.
2. the response is not redirected to a different lifecycle component via IMessageBuilder::redirectResponse().

This call returns as soon as Message Router accepts the request. The message may not have been delivered to its final destination. If the message opted in to delivery confirmation via IMessagePropertiesBuilder::requireDeliveryConfirmation(), IMessageListener::onMessageDelivered() fires on the supplied listener (if non-null) after all targets have either received or rejected the message. Pass nullptr for a true fire-and-forget send: no callbacks fire for delivery, response, or error. The nullable here represents an absent listener, not a wildcard. The implementation pins the listener for the duration of in-flight events for this send (until onMessageDelivered, the response, or onError fires; or until timeout / disconnect). Callers do not need to manage listener lifetime explicitly.

​

Parameters

message

IMessage* — Required The message to send.

listener

IMessageListener? — Optional Receives onMessageDelivered, onError, and onMessage (if the response is not redirected). May be nullptr for fire-and-forget.

​

Throws

• com.amazon.apmf.InvalidArgumentError — if message is empty.
• com.amazon.apmf.SecurityError — if the caller doesn’t have necessary permissions to send the message.

---

​

registerMessageFilter()

IMessageFilterSubscription* registerMessageFilter(IMessageFilter*[] messageFilters, IMessageListener* listener)

Registers a set of new message filters with the message router and returns a subscription handle. The supplied listener receives messages that match any of these filters. Runtime filters are active only for the duration of the application lifetime. Developers may instead use Kepler Tasks to listen to broadcast:// or unicast:// scheme messages. The manifest can be used to specify launchable interaction points that other apps may trigger. Message delivery requires matching against all installed filters. Registering for too many filters impacts the performance of the app. Messages will be delivered to all matching registered filters. The listener is held by the subscription until the subscription is dropped or unsubscribe() is called; callers do not need to manage listener lifetime explicitly.

​

Parameters

messageFilters

IMessageFilter*[] — Required The list of Message Filters to register.

listener

IMessageListener* — Required Receives onMessage for any message that matches any registered filter, plus onError for receive-side errors.

​

Returns

IMessageFilterSubscription* A subscription handle that can be used to unsubscribe.

​

Throws

• com.amazon.apmf.InvalidArgumentError — if messageFilters is empty.
• com.amazon.apmf.SecurityError — if the caller doesn’t have necessary permissions to register the filter.

---

​

canSendUri()

bool canSendUri(string uri)

Checks whether the caller is permitted to send a message to the target URI. Most of the time it is simpler to directly call send() and handle the errors it throws; however, in flows where a UI artifact must not even be shown unless the eventual send would succeed, this call lets the caller decide upfront. Uses the caller’s own credential, drawn from the IPC call context. Use canSendUriForCredential() to perform the same check on behalf of a different credential. This call returns as soon as Message Router validates the request.

​

Parameters

uri

string — Required The URI to check.

​

Returns

bool True if the caller would be permitted to send a message with the target URI, false otherwise.

---

​

canSendUriForCredential()

bool canSendUriForCredential(com.amazon.apmf.ICredential* credential, string uri)

Checks whether a given credential is permitted to send a message to the target URI. Most of the time it is simpler to directly call send() and handle the errors it throws; however, in flows where a UI artifact must not even be shown unless the eventual send would succeed, this call lets the caller decide upfront. The credential whose permissions are evaluated is supplied explicitly. Callers that forward or proxy sends on behalf of another principal can pass that principal’s credential here to evaluate permissions from the originator’s perspective rather than the caller’s own. This call returns as soon as Message Router validates the request.

​

Parameters

credential

com.amazon.apmf.ICredential* — Required The credential whose permissions are being queried. Typically obtained from IMessage::getSenderCredential() of a previously received message, or from the IPC API call context of an in-flight service request.

uri

string — Required The URI to check.

​

Returns

bool True if credential would be permitted to send a message with the target URI, false otherwise. Returns false (does not throw) when credential refers to an unknown or expired principal.

---

​

canReceiveUriForCredential()

bool canReceiveUriForCredential(com.amazon.apmf.ICredential* credential, string uri)

Checks whether a given credential is permitted to receive a message addressed to the target URI — i.e., whether the credential is allowed to register a filter that would match the URI, or to be selected as the unicast/component-scheme recipient for it. Symmetric counterpart to canSendUriForCredential. Useful for callers that forward or proxy filter registrations or message dispatch on behalf of another principal and need to validate that principal’s receive-side permissions upfront. This call returns as soon as Message Router validates the request.

​

Parameters

credential

com.amazon.apmf.ICredential* — Required The credential whose permissions are being queried. Typically obtained from IMessage::getSenderCredential() of a previously received message, or from the IPC API call context of an in-flight service request.

uri

string — Required The URI to check.

​

Returns

bool True if credential would be permitted to receive a message with the target URI, false otherwise. Returns false (does not throw) when credential refers to an unknown or expired principal.

---