namespace ara::com

The enumeration ComErrc defines, according to [SWS_CM_10432], the standardized error codes of ara::com::ComErrorDomain for recoverable errors according to EXP ARAComAPI §2 “Recoverable Errors”. It is transported in return types such as ara::core::Result or ara::core::Future of synchronous and asynchronous APIs of Communication Management to signal functional error causes precisely in the client or server context.

The enumerators cover specific error cases along the service life cycle and data transmission:

• Service life cycle and binding: kServiceNotOffered indicates that a service has not yet been offered via OfferService() ([SWS_CM_00101]), while kServiceNotAvailable signals the intermittent loss. kInstanceIDNotResolvable occurs when a InstanceSpecifier cannot be resolved ([SWS_CM_00118]).
• Event and sample subscriptions: kMaxSamplesExceeded warns of exceeding promised SamplePtr quotas, and kMaxSampleCountNotRealizable reports unsuitable values during resubscription via [SWS_CM_00141].
• Fields and transmission: kFieldValueNotInitialized indicates missing initialization prior to Update() ([SWS_CM_00119]), kFieldSetHandlerNotSet a missing setter handler. Local network issues, such as during trigger transmission via [SWS_CM_00721], result in kCommunicationFailure ([SWS_CM_10517]). In addition, kMinimumSendIntervalViolationError penalizes cycle rate violations and kUnknownApplicationError unexpected server errors ([SWS_CM_10432]).

As a pure enumeration type, ComErrc has no state of its own; read and comparison operations on error values are therefore likely to be concurrently safe in the calling thread. Question Q-013822ee5711df2b (open) The actual error checking is the responsibility of the application after evaluating the respective result object.

The enumeration ara::com::MethodCallProcessingMode defines the processing modes for incoming method calls on a service instance [SWS_CM_00301]. It is passed as a parameter to the constructors of the skeleton classes, with the default value ara::com::MethodCallProcessingMode::kEvent predefined [SWS_CM_00130], [SWS_CM_00152], [SWS_CM_00153].

The enumerators control the concurrency and execution context of the service methods [SWS_CM_00301]:

• kPoll: Polling mode. Incoming calls from service consumers are not executed automatically. The service implementation actively controls their execution by calling ProcessNextMethodCall() [SWS_CM_00199]. The pending method is processed synchronously in the context of this call. This ensures full control over thread and context switches on the service side ARAComAPI §6.3.3 “Event Buffering Approaches”.
• kEvent: Event-driven and concurrent mode for parallel processing of incoming calls.
• kEventSingleThread: Event-driven, sequential mode for single execution of method calls.

Error Handling and Restrictions:

• If an invalid mode is passed to a skeleton constructor, violation WrongMethodCallProcessingModeViolation occurs [SWS_CM_00130], [SWS_CM_00153].
• Calling ProcessNextMethodCall() on a skeleton constructed with kEvent likewise leads to a WrongMethodCallProcessingModeViolation [SWS_CM_00199] (interpretation: this is likely to apply to kEventSingleThread as well, since the method is intended only for kPoll). Question Q-bcd9f07119db44fb (open)

The enumeration SubscriptionState [SWS_CM_00310] represents the current state of a subscription in namespace ara::com based on type std::uint8_t. It defines three distinct states:

• kNotSubscribed: The subscription is inactive.
• kSubscriptionPending: The subscription is still pending or the connection is being re-established after a failure.
• kSubscribed: The subscription is active.

The GetSubscriptionState() method serves for synchronous querying, which is provided on proxy events [SWS_CM_00316], proxy fields [SWS_CM_11604], and triggers [SWS_CM_01105] as well as skeleton triggers [SWS_CM_01109]. All of these query functions are declared as noexcept and guarantee complete exception safety.

For asynchronous reactions to status changes, applications can register a callback of type SubscriptionStateChangeHandler via SetSubscriptionStateChangeHandler() [SWS_CM_00311] [SWS_CM_00333]. If an invalid or empty handler is passed, the violation InvalidHandlerViolation occurs [SWS_CM_00333]. Deregistration is performed via UnsetSubscriptionStateChangeHandler() [SWS_CM_00334]. Furthermore, a template overload with ExecutorT allows specifying the execution context for the callback [SWS_CM_11354].

In the lifecycle of a proxy instance, SubscriptionState is closely interlinked with automatic updating: If a service instance fails, method calls fail and GetSubscriptionState() returns kSubscriptionPending for previously subscribed events ARAComAPI §6.1 “Auto Updating of Proxy Instance”. As soon as the service instance is reachable again via Service Discovery, communication management updates the connection transparently; GetSubscriptionState() then automatically returns kSubscribed again AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2. Manual re-creation of the proxy or re-subscribing is not required in this process.

The type alias SubscriptionStateChangeHandler in namespace ara::com is declared as std::function<void(SubscriptionState)> in header file ara/com/types.h ([SWS_CM_00311]). It specifies the function signature for application callbacks triggered as soon as the ara::com::SubscriptionState of a subscribed proxy event changes ([SWS_CM_00311], EXP_ARAComAPI §5.3 “Proxy Class API’s”). When called, the new subscription state is passed directly as a parameter; a return value is not provided ([SWS_CM_00311]).

Registration of the handler is performed via method SetSubscriptionStateChangeHandler() of the respective proxy class (EXP_ARAComAPI §5.3.1 “Proxy Class API’s”, EXP_ARAComAPI §5.3 “Proxy Class API’s”). This operation returns a ara::core::Result<void> (EXP_ARAComAPI §5.3 “Proxy Class API’s”), through which application developers can synchronously check possible errors during registration. Specific removal of the registered callback is performed by calling UnsetSubscriptionStateChangeHandler() according to [SWS_CM_00334] (EXP_ARAComAPI §1 “Introduction”, EXP_ARAComAPI §5.3.1 “Proxy Class API’s”).

Regarding workflow and concurrency, state notification occurs asynchronously. Calling of the handler is likely to occur in the thread context of the communication infrastructure (interpretation). Question Q-8dda0cd4de0070bf (open) Therefore, the implementation of the callback must return promptly and be designed to be reentrant or thread-safe. Interplay of the handler integrates closely into the lifecycle of the event subscription, particularly in combination with Subscribe(), Unsubscribe(), and GetSubscriptionState() (EXP_ARAComAPI §5.3.1 “Proxy Class API’s”).

use

The global function GetComErrorDomain in namespace ara::com provides a reference to the error domain object ara::com::ComErrorDomain [SWS_CM_11334]. The declaration is included via header ara/com/com_error_domain.h and takes the form of a synchronous, parameterless call SWS CommunicationManagement §8.12.3.1.1 “GetComErrorDomain”. As a return value, the function yields a constant reference of type const ara::core::ErrorDomain&, which represents the communication error domain in the system.

Error Handling and Exception Safety

The interface is explicitly declared as noexcept and is considered exception safe (exception safe) [SWS_CM_11334]. Because the function call is always successful, no runtime errors occur. Callers therefore do not need to provide error handling for the function call itself. Specific error codes, feedback channels, or reports to DET or DEM are not defined in the specification for this retrieval.

Concurrency and Interaction

Thanks to the declaration with constexpr and noexcept, the function is expected to be stateless, free of side effects, as well as fully reentrant and thread-safe; presumably it can also be executed at compile time. Question Q-21aafe1fdcb5997b (open) The provided error domain serves in the overall system as a reference instance to verify error codes from operations of Communication Management based on their domain membership and to distinguish them from other error sources [SWS_CM_11334].

The helper function ara::com::MakeErrorCode serves to create an instance of ara::core::ErrorCode ([SWS_CM_11335], SWS CommunicationManagement §8.12.3.1.2 “MakeErrorCode”). It is declared via header file #include "ara/com/com_error_domain.h" in namespace ara::com. As input parameters, it accepts error number code of type ara::com::ComErrc as well as vendor-specific additional data data of type ara::core::ErrorDomain::SupportDataType and returns the corresponding error object synchronously.

Regarding execution safety, the function is specified as noexcept and expressly classified as exception safe (“exception safe”) ([SWS_CM_11335]). Runtime notifications via DET or DEM are not intended for this helper function, as it exclusively serves for constructing error objects. Due to declaration as constexpr and noexcept, the function is likely side-effect-free and reentrant, whereby calls are also permissible at compile time and from concurrent contexts. Question Q-43f118920f402d86 (open)

The architectural pattern follows the platform-wide error model of Adaptive AUTOSAR and is provided analogously for adjacent functional domains: Function ara::com::e2e::MakeErrorCode exists for end-to-end protection ([SWS_CM_12511], SWS CommunicationManagement §8.15.2.1.2 “MakeErrorCode”), while apext::com::secoc::MakeErrorCode is available for security functions ([SWS_CM_12522], SWS CommunicationManagement §C.2.2.1.2 “MakeErrorCode”).