Member Reference#

This section contains all members tagged with @api.

template<template<class> class T>
using score::mw::com::AsProxy = impl::AsProxy<T>#

Interpret an interface that follows our traits as proxy (cf. impl/traits.h).

Feature API:

template<template<class> class T>
using score::mw::com::AsSkeleton = impl::AsSkeleton<T>#

Interpret an interface that follows our traits as skeleton (cf. impl/traits.h).

Feature API:

using score::mw::com::ComErrc = score::mw::com::impl::ComErrc#

Error codes for COM API operations as defined by AUTOSAR SWS Communication Management.

Feature API:

using score::mw::com::ComErrorDomain = score::mw::com::impl::ComErrorDomain#

Error domain providing human-readable messages for COM error codes.

Feature API:

using score::mw::com::DataTypeMetaInfo = impl::DataTypeMetaInfo#

Meta information about a data type, used for generic services.

Feature API:

using score::mw::com::EventInfo = impl::EventInfo#

Information required to create a generic event.

Feature API:

using score::mw::com::EventReceiveHandler = impl::EventReceiveHandler#

Callback for event notifications on proxy side. \requirement SWS_CM_00309.

Feature API:

using score::mw::com::FindServiceHandle = ::score::mw::com::impl::FindServiceHandle#

Handle for service discovery operations. See StartFindService() and StopFindService() for more information.

Feature API:

template<typename T>
using score::mw::com::FindServiceHandler = ::score::mw::com::impl::FindServiceHandler<T>#

Callback that notifies the callee about service availability changes. See ProxyBase::StartFindService for more information.

Feature API:

using score::mw::com::GenericProxy = impl::GenericProxy#

A type erased proxy that can be used to read the raw data from a skeleton without knowing the SampleType.

Feature API:

using score::mw::com::GenericSkeleton = impl::GenericSkeleton#

A type erased skeleton that can be used to offer a service without knowing the SampleType.

Feature API:

using score::mw::com::GenericSkeletonEvent = impl::GenericSkeletonEvent#

A type erased skeleton event that can be used to send data without knowing the SampleType.

Feature API:

using score::mw::com::GenericSkeletonServiceElementInfo = impl::GenericSkeletonServiceElementInfo#

Parameters for creating a GenericSkeleton.

Feature API:

using score::mw::com::HandleType = ::score::mw::com::impl::HandleType#

Handle to a service instance.

Feature API:

using score::mw::com::InstanceIdentifier = ::score::mw::com::impl::InstanceIdentifier#

Represents a specific instance of a service. \requirement SWS_CM_01019.

Feature API:

using score::mw::com::InstanceIdentifierContainer = std::vector<InstanceIdentifier>#

The container holds a list of instance identifiers and is used as a return value of the ResolveInstanceIDs method. \requirement SWS_CM_00319.

Feature API:

using score::mw::com::InstanceSpecifier = ::score::mw::com::impl::InstanceSpecifier#

Identifier for an application port. Maps design to deployment. \requirement SWS_CM_00350.

Feature API:

template<typename ReturnType>
using score::mw::com::MethodInArgTypePtr = impl::MethodInArgPtr<ReturnType>#

Feature API:

A pointer type which carries a pointer to a method input argument value in shared memory.

template<typename ReturnType>
using score::mw::com::MethodReturnTypePtr = impl::MethodReturnTypePtr<ReturnType>#

Feature API:

A pointer type which carries a pointer to the method return value in shared memory.

using score::mw::com::ReceiveHandlerRegistrationChangedCallback = impl::ReceiveHandlerRegistrationChangedCallback#

A callback that can be registered on a GenericSkeletonEvent to be notified about changes in the availability of receive-handlers for this event.

Feature API:

template<typename T>
using score::mw::com::ServiceHandleContainer = ::score::mw::com::impl::ServiceHandleContainer<T>#

Container with handles representing currently available service instances. See StartFindService() for more information.

Feature API:

using score::mw::com::SubscriptionState = ::score::mw::com::impl::SubscriptionState#

Subscription state of a proxy event. See ProxyEvent::GetSubscriptionStatus for slightly more information.

Feature API:

using score::mw::com::WithGetter = impl::WithGetter#

Field tag types used in service-interface definitions to enable Get/Set/Notifier on a field.

Feature API:

template<template<class> class T>
using score::mw::com::impl::AsProxy = ProxyWrapperClass<T>#

Interpret an interface that follows our traits as proxy (see description above).

Feature API:

template<template<class> class T>
using score::mw::com::impl::AsSkeleton = SkeletonWrapperClass<T>#

Interpret an interface that follows our traits as skeleton (see description above).

Feature API:

enum class score::mw::com::impl::ComErrc : score::result::ErrorCode#

Error codes for the mw::com API.

Feature API:

Enum values map 1:1 to the Communication Management error codes. \requirement SWS_CM_10432 \threadsafe

Values:

enumerator kInvalid#
enumerator kServiceNotAvailable#
enumerator kMaxSamplesReached#
enumerator kBindingFailure#
enumerator kGrantEnforcementError#
enumerator kPeerIsUnreachable#
enumerator kFieldValueIsNotValid#
enumerator kSetHandlerNotSet#
enumerator kUnsetFailure#
enumerator kSampleAllocationFailure#
enumerator kIllegalUseOfAllocate#
enumerator kServiceNotOffered#
enumerator kCommunicationLinkError#
enumerator kNoClients#
enumerator kCommunicationStackError#
enumerator kMaxSampleCountNotRealizable#
enumerator kMaxSubscribersExceeded#
enumerator kErroneousFileHandle#
enumerator kCouldNotExecute#
enumerator kInvalidInstanceIdentifierString#
enumerator kInvalidBindingInformation#
enumerator kEventNotExisting#
enumerator kNotSubscribed#
enumerator kInvalidConfiguration#
enumerator kInvalidMetaModelShortname#
enumerator kServiceInstanceAlreadyOffered#
enumerator kCouldNotRestartProxy#
enumerator kNotOffered#
enumerator kInstanceIDCouldNotBeResolved#
enumerator kFindServiceHandlerFailure#
enumerator kInvalidHandle#
enumerator kCallQueueFull#
enumerator kServiceElementAlreadyExists#
enumerator kMethodBindingDisabled#
enumerator kNumEnumElements#
inline std::string_view score::mw::com::impl::ComErrorDomain::MessageFor(const score::result::ErrorCode &code) const noexcept final override

Translates an error code into a human readable message.

Todo:

Gcc compiler bug leads to a compiler warning if override is not added, even if final keyword is there (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=78010). When bug is fixed, remove the override keyword from the MessageFor function signature and the AUTOSAR.MEMB.VIRTUAL.SPEC klocwork suppression.

Feature API:

This function is required by the std::error_domain interface

Parameters:

code – The error code to translates

Returns:

returns a string view to the human readable message \threadsafe

score::mw::com::impl::FindServiceHandle::FindServiceHandle(FindServiceHandle &&other) noexcept = default

MoveAssignment for FindServiceHandle.

Feature API:

Parameters:

other – The FindServiceHandle *this shall be constructed from

Post:

*this == other

Returns:

The FindServiceHandle that was constructed

score::mw::com::impl::FindServiceHandle::FindServiceHandle(const FindServiceHandle &other) = default

CopyConstructor for FindServiceHandle.

Feature API:

Parameters:

other – The FindServiceHandle to copy from

Returns:

The FindServiceHandle that was constructed

friend bool score::mw::com::impl::FindServiceHandle::operator<(const FindServiceHandle &lhs, const FindServiceHandle &rhs) noexcept

LessThanComparable operator.

Feature API:

Parameters:
Returns:

true if lhs is less then rhs, false otherwise

friend mw::log::LogStream &score::mw::com::impl::FindServiceHandle::operator<<(mw::log::LogStream &log_stream, const FindServiceHandle &find_service_handle)

Stream operator which enables logging of FindServiceHandle via mw::log::LogStream.

Feature API:

Parameters:

  • log_stream – The log stream to write to

  • find_service_handle – The FindServiceHandle to log

Returns:

The log stream passed in as parameter

friend std::ostream &score::mw::com::impl::FindServiceHandle::operator<<(std::ostream &ostream_out, const FindServiceHandle &find_service_handle)

Stream operator which enables logging of FindServiceHandle via std::ostream.

Feature API:

Parameters:

  • ostream_out – The output stream to write to

  • find_service_handle – The FindServiceHandle to log

Returns:

The output stream passed in as parameter

FindServiceHandle &score::mw::com::impl::FindServiceHandle::operator=(FindServiceHandle &&other) noexcept = default

MoveAssignment for FindServiceHandle.

Feature API:

Parameters:

other – The FindServiceHandle *this shall be constructed from

Post:

*this == other

Returns:

The FindServiceHandle that was constructed

FindServiceHandle &score::mw::com::impl::FindServiceHandle::operator=(const FindServiceHandle &other) = default

CopyAssignment for FindServiceHandle.

Feature API:

Parameters:

other – The FindServiceHandle *this shall be constructed from

Post:

*this == other

Returns:

The FindServiceHandle that was constructed

friend bool score::mw::com::impl::FindServiceHandle::operator==(const FindServiceHandle &lhs, const FindServiceHandle &rhs) noexcept

Compares two instances for equality.

Feature API:

Parameters:

  • lhs – The first instance to check for equality

  • rhs – The second instance to check for equality

Returns:

true if lhs and rhs equal, false otherwise

template<typename T>
using score::mw::com::impl::FindServiceHandler = score::cpp::callback<void(ServiceHandleContainer<T>, FindServiceHandle)>#

A function wrapper for the handler function that gets called by the Communication Management software in case the service availability changes.

Feature API:

It takes as input parameter a handle container containing handles for all matching service instances and a FindServiceHandle which can be used to invoke StopFindService (see [SWS_CM_00125]) from within the FindServiceHandler.

\requirement SWS_CM_00383

static Result<GenericProxy> score::mw::com::impl::GenericProxy::Create(HandleType instance_handle) noexcept

Exception-less GenericProxy constructor.

Feature API:

Parameters:

instance_handle – Handle to the instance

Returns:

Result containing the created GenericProxy instance or an error code.

EventMapView score::mw::com::impl::GenericProxy::GetEvents() const noexcept

Returns a read-only view to the name-keyed map of events.

Feature API:

Note

The returned view is valid as long as the GenericProxy lives.

Returns:

View to the event map.

static score::Result<InstanceIdentifier> score::mw::com::impl::InstanceIdentifier::Create(std::string &&serialized_format) noexcept

Exception-less constructor to create InstanceIdentifier from a serialized InstanceIdentifier created with InstanceIdentifier::ToString().

Feature API:

Parameters:

serialized_format – The serialized format to create the InstanceIdentifier from

Returns:

The created InstanceIdentifier or an error

Pre:

The score::mw::com::impl::Runtime singleton must have been created (then the configuration is “locked”) before calling this API, i.e. Only then has a valid Configuration pointer been registered (by the Runtime constructor) into which the reconstructed deployments are added. Currently, there is no public API whose sole purpose is to initialize/create the Runtime singleton; in practice any prior public score::mw::com call that reaches Runtime::getInstance() (e.g. creating a Skeleton/Proxy, FindService, or - as a last resort - score::mw::com::runtime::ResolveInstanceIDs called with a dummy InstanceSpecifier) triggers this. If the configuration has not been set, kInvalidConfiguration is returned.

score::mw::com::impl::InstanceIdentifier::InstanceIdentifier(InstanceIdentifier&&) noexcept = default

Move constructor for InstanceIdentifier.

Feature API:

Parameters:

other – The InstanceIdentifier to move from

Post:

*this == other

Returns:

The moved InstanceIdentifier

score::mw::com::impl::InstanceIdentifier::InstanceIdentifier(const InstanceIdentifier&) = default

Copy constructor for InstanceIdentifier.

Feature API:

Parameters:

other – The InstanceIdentifier to copy from

Returns:

The InstanceIdentifier that was constructed

std::string_view score::mw::com::impl::InstanceIdentifier::ToString() const noexcept

Returns the serialized form of the unknown internals of this class as a meaningful string.

Feature API:

Returns:

A non-owning string representation of the internals of this class

friend bool score::mw::com::impl::InstanceIdentifier::operator<(const InstanceIdentifier &lhs, const InstanceIdentifier &rhs) noexcept

LessThanComparable operator.

Feature API:

Parameters:
Returns:

true if *this is less then other, false otherwise

InstanceIdentifier &score::mw::com::impl::InstanceIdentifier::operator=(InstanceIdentifier &&other) noexcept = default

MoveAssignment for InstanceIdentifier.

Feature API:

Parameters:

other – The InstanceIdentifier *this shall be constructed from

Post:

*this == other

Returns:

The InstanceIdentifier that was constructed

InstanceIdentifier &score::mw::com::impl::InstanceIdentifier::operator=(const InstanceIdentifier &other) = default

CopyAssignment for InstanceIdentifier.

ctor from serialized representation.

Constructor is required by adaptive AUTOSAR Standard. But it uses exceptions, thus we will not implement it.

explicit InstanceIdentifier(std::string_view value);

Feature API:

Parameters:

other – The InstanceIdentifier *this shall be constructed from

Post:

*this == other

Returns:

The InstanceIdentifier that was constructed

friend bool score::mw::com::impl::InstanceIdentifier::operator==(const InstanceIdentifier &lhs, const InstanceIdentifier &rhs) noexcept

Compares two instances for equality.

Feature API:

Parameters:

  • lhs – The first instance to check for equality

  • rhs – The second instance to check for equality

Returns:

true if other and *this equal, false otherwise

static score::Result<InstanceSpecifier> score::mw::com::impl::InstanceSpecifier::Create(std::string &&shortname_path) noexcept

Create an InstanceSpecifier from a shortname path.

Feature API:

Parameters:

shortname_path – The shortname path to create the InstanceSpecifier from.

Returns:

A Result containing the created InstanceSpecifier or an error.

std::string_view score::mw::com::impl::InstanceSpecifier::ToString() const noexcept

Convert the InstanceSpecifier to a string representation.

Feature API:

Returns:

A string representation of the InstanceSpecifier.

static Result<ServiceHandleContainer<HandleType>> score::mw::com::impl::ProxyBase::FindService(InstanceIdentifier instance_identifier) noexcept#

Tries to find a service that matches the given instance identifier synchronously.

Feature API:

Does a synchronous one-shot lookup/find, which service instance(s) matching the specifier are there.

Parameters:

instance_identifier – The instance_identifier of the service.

Returns:

A result which on success contains a list of found handles that can be used to create a proxy. On failure, returns an error code.

static Result<ServiceHandleContainer<HandleType>> score::mw::com::impl::ProxyBase::FindService(InstanceSpecifier specifier) noexcept#

Tries to find a service that matches the given specifier synchronously.

Feature API:

Does a synchronous one-shot lookup/find, which service instance(s) matching the specifier are there.

Parameters:

specifier – The instance specifier of the service.

Returns:

A result which on success contains a list of found handles that can be used to create a proxy. On failure, returns an error code. \requirement SWS_CM_00622

Warning

doxygenfunction: Unable to resolve function “score::mw::com::impl::ProxyBase::GetHandle” with arguments () const in doxygen xml output for project “doxygen_build” from directory: score/mw/com/design/doxygen_build/xml. Potential matches: 

- const HandleType &GetHandle() const & noexcept
static Result<FindServiceHandle> score::mw::com::impl::ProxyBase::StartFindService(FindServiceHandler<HandleType> handler, InstanceIdentifier instance_identifier) noexcept#

Starts asynchronous service discovery that matches the given instance identifier.

Feature API:

Initiates a continuous service discovery operation. The provided handler will be called whenever matching service instances become available or unavailable.

Parameters:

  • handler – The callback handler to be invoked when service availability changes.

  • instance_identifier – The instance identifier of the service to find.

Returns:

A result which on success contains a handle to control the find operation. On failure, returns an error code.

static Result<FindServiceHandle> score::mw::com::impl::ProxyBase::StartFindService(FindServiceHandler<HandleType> handler, InstanceSpecifier instance_specifier) noexcept#

Starts asynchronous service discovery that matches the given instance specifier.

Feature API:

Initiates a continuous service discovery operation. The provided handler will be called whenever matching service instances become available or unavailable.

Parameters:

  • handler – The callback handler to be invoked when service availability changes.

  • instance_specifier – The instance specifier of the service to find.

Returns:

A result which on success contains a handle to control the find operation. On failure, returns an error code.

static score::Result<void> score::mw::com::impl::ProxyBase::StopFindService(const FindServiceHandle handle) noexcept#

Stops an ongoing asynchronous service discovery operation.

Feature API:

Terminates the service discovery initiated by StartFindService. After this call, the associated handler will no longer be invoked.

Parameters:

handle – The handle returned by StartFindService identifying the find operation to stop.

Returns:

A result indicating success or failure of stopping the find operation.

template<typename SampleDataType>
class ProxyEvent : public score::mw::com::impl::ProxyEventBase#

This is the user-visible class of an event that is part of a proxy. It contains ProxyEvent functionality that requires knowledge of the SampleType. All type agnostic functionality is stored in the base class, ProxyEventBase.

The class itself is a concrete type. However, it delegates all actions to an implementation that is provided by the binding the proxy is operating on.

Template Parameters:

SampleDataType – Type of data that is transferred by the event.

Public Types

using SampleType = SampleDataType#

Public Functions

ProxyEvent(const std::string_view event_name, std::unique_ptr<ProxyEventBinding<SampleType>> proxy_event_binding)#

Constructor which is dispatched to by the other public constructors.

Instantiates the base class and members of ProxyEvent. Should only be called directly in tests.

Parameters:

proxy_binding – The binding that shall be associated with this proxy.

ProxyEvent(ProxyBase &base, const std::string_view event_name, Result<std::unique_ptr<ProxyEventBinding<SampleType>>> proxy_event_binding, FieldOnlyConstructorEnabler)#

Constructor that allows to set the binding directly.

This is used by ProxyField to pass in a ProxyEventBinding created using the ProxyFieldBindingFactory.

Parameters:

proxy_binding – The binding that shall be associated with this proxy.

ProxyEvent(ProxyBase &base, const std::string_view event_name)#

Constructs a ProxyEvent by querying the base proxie’s ProxyBinding for the respective ProxyEventBinding.

Todo:

Remove unneeded parameter once we get these information from the configuration

Parameters:

  • base – Proxy that contains this event

  • event_name – Event name of the event, taken from the AUTOSAR model

ProxyEvent(const ProxyEvent&) = delete#

A ProxyEvent shall not be copyable.

ProxyEvent &operator=(const ProxyEvent&) & = delete#
ProxyEvent(ProxyEvent &&other) noexcept = default#

A ProxyEvent shall be movable.

ProxyEvent &operator=(ProxyEvent &&other) noexcept = default#
~ProxyEvent() override = default#
template<typename F>
Result<std::size_t> GetNewSamples(F &&receiver, std::size_t max_num_samples) noexcept#

Receive pending data from the event.

Feature API:

The user needs to provide a callable that fulfills the following signature: void F(SamplePtr<const SampleType>) noexcept. This callback will be called for each sample that is available at the time of the call. Notice that the number of callback calls cannot exceed std::min(GetFreeSampleCount(), max_num_samples) times.

Template Parameters:

F – Callable with the signature void(SamplePtr<const SampleType>) noexcept

Parameters:

  • receiver – Callable with the appropriate signature. GetNewSamples will take ownership of this callable.

  • max_num_samples – Maximum number of samples to return via the given callable.

Returns:

Number of samples that were handed over to the callable or an error.

inline void InjectMock(IProxyEvent<SampleType> &proxy_event_mock)#
std::size_t score::mw::com::impl::ProxyEventBase::GetFreeSampleCount() const noexcept#

Get the number of samples that can still be received by the user of this event.

Feature API:

If this returns 0, the user first has to drop at least one SamplePtr before it is possible to receive data via GetNewSamples again. If there is no subscription for this event, the returned value is unspecified.

Returns:

Number of samples that can still be received.

Result<std::size_t> score::mw::com::impl::ProxyEventBase::GetNumNewSamplesAvailable() const noexcept#

Returns the number of new samples a call to GetNewSamples() would currently provide if the max_sample_count set in the Subscribe call and GetNewSamples call were both infinitely high.

Feature API:

E.g. If there are 10 available / valid samples, but the max_sample_count set in the Subscribe() call was 2, then GetNumNewSamplesAvailable() would return 10 while a call to GetNewSamples(2) would only receive 2 samples. This is a proprietary extension to the official ara::com API. It is useful in resource sensitive setups, where the user wants to work in polling mode only without registered async receive-handlers. For further details see //score/mw/com/design/extensions/README.md.

Returns:

Either 0 if no new samples are available (and GetNewSamples() wouldn’t return any) or N, where 1 <= N <= actual new samples. I.e. an implementation is allowed to report a lower number than actual new samples, which would be provided by a call to GetNewSamples().

SubscriptionState score::mw::com::impl::ProxyEventBase::GetSubscriptionState() const noexcept#

Get the subscription state of this event.

Feature API:

This method can always be called regardless of the state of the event.

Returns:

Subscription state of the event.

inline bool score::mw::com::impl::ProxyEventBase::IsBindingValid() const noexcept#

Checks if the binding is valid.

Feature API:

Returns:

True if the binding is valid, false otherwise.

Result<void> score::mw::com::impl::ProxyEventBase::SetReceiveHandler(EventReceiveHandler handler) noexcept#

Sets the handler to be called, whenever a new event-sample has been received.

Feature API:

Generally a ReceiveHandler has no restrictions on what mw::com API it is allowed to call. It is especially allowed to call all public APIs of the Event instance on which it had been set/registered as long as it obeys the general requirement, that API calls on a Proxy/Proxy event are thread safe/can’t be called concurrently.

Attention

This function MUST NOT be called from the context of a ReceiveHandler registered for this event! It makes semantically not really sense to register a “new” ReceiveHandler from the context of an already running ReceiveHandler. We also see no use cases for it and won’t support it therefore.

Parameters:

handler – user provided handler to be called

Result<void> score::mw::com::impl::ProxyEventBase::SetSubscriptionStateChangeHandler(SubscriptionStateChangeHandler handler) noexcept#

Sets/Registers a SubscriptionStateChangeHandler for this event. This handler will be called whenever the subscription state of this event changes.

Feature API:

Note

An already set/registered SubscriptionStateChangeHandler will be silently overridden.

Parameters:

handler –

Result<void> score::mw::com::impl::ProxyEventBase::Subscribe(const std::size_t max_sample_count) noexcept#

Subscribe to the event.

Feature API:

This will initialize the event so that event data can be received once it arrives.

Parameters:

max_sample_count – Specify the maximum number of concurrent samples that this event shall be able to offer to the using application.

Returns:

On failure, returns an error code.

Result<void> score::mw::com::impl::ProxyEventBase::UnsetReceiveHandler() noexcept#

Removes any ReceiveHandler registered via SetReceiveHandler.

Feature API:

Result<void> score::mw::com::impl::ProxyEventBase::UnsetSubscriptionStateChangeHandler() noexcept#

Unsets/Unregisters a SubscriptionStateChangeHandler for this event. After this method returns, it is guaranteed, that the previously registered handler is neither active nor will be called anymore.

Feature API:

void score::mw::com::impl::ProxyEventBase::Unsubscribe() noexcept#

End subscription to an event and release needed resources.

Feature API:

It is illegal to call this method while data is still held by the application in the form of SamplePtr. Doing so will result in undefined behavior. An eventually currently registered ReceiveHandler will get removed (needs to be set again for a new subscription) and therefore, this method will “synchronize” with a currently running ReceiveHandler and will only finish after any running ReceiveHandler has ended. After a call to this method, the event behaves as if it had just been constructed.

template<typename SampleDataType, typename ...Tags>
class ProxyFieldImpl : public score::mw::com::impl::ProxyFieldBase#

This is the user-visible class of a field that is part of a proxy. It delegates all functionality to ProxyEvent.

Template Parameters:

Subclassed by score::mw::com::impl::ProxyField< SampleType, Tags… >

Public Types

using FieldType = SampleDataType#

Public Functions

inline ProxyFieldImpl(const std::string_view field_name, std::unique_ptr<ProxyEventBinding<FieldType>> event_binding, std::unique_ptr<ProxyMethodBinding> set_method_binding = nullptr, std::unique_ptr<ProxyMethodBinding> get_method_binding = nullptr)#

Testing ctor that delegates to the production ctor that accepts mock bindings directly, this can only be used in test code.

The template tags do not gate this overload; they continue to control which parts of the public API (Get, Set, Subscribe, …) are available on the resulting object. The event binding parameter is required (non default) to disambiguate this overload from the production ctor.

Parameters:

  • proxy_base – Parent proxy that owns this field’s registration.

  • field_name – Field’s name as it appears in the deployment.

  • event_binding – Mock event binding. Must be provided (use nullptr if no event binding is needed).

  • set_method_binding – Optional mock Set-method binding. If nullptr, no ProxyMethod is built for Set.

  • get_method_binding – Optional mock Get-method binding. If nullptr, no ProxyMethod is built for Get.

inline ProxyFieldImpl(ProxyBase &proxy_base, const std::string_view field_name)#

Production ctor used by the end users.

The Make*IfEnabled helpers consult the tag pack at compile time and return nullptr when their corresponding tag is absent, so the same body produces the correct dispatch for every valid tag combination. The class-level static_assert ensures that at least one of WithGetter or WithNotifier is present.

Parameters:

  • proxy_base – Parent proxy that owns this field’s registration.

  • field_name – Field’s name as it appears in the deployment.

ProxyFieldImpl(const ProxyFieldImpl&) = delete#

A ProxyFieldImpl shall not be copyable.

ProxyFieldImpl &operator=(const ProxyFieldImpl&) = delete#
ProxyFieldImpl(ProxyFieldImpl&&) noexcept = default#

A ProxyField shall be moveable.

ProxyFieldImpl &operator=(ProxyFieldImpl&&) noexcept = default#
~ProxyFieldImpl() noexcept = default#
template<typename ReceiverType, typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<std::size_t> GetNewSamples(ReceiverType &&receiver, const std::size_t max_num_samples) noexcept#

Receive pending data from the field.

Feature API:

The user needs to provide a callable that fulfills the following signature: void(SamplePtr<const FieldType>) noexcept. This callback will be called for each sample that is available at the time of the call. Notice that the number of callback calls cannot exceed std::min(GetFreeSampleCount(), max_num_samples) times.

Template Parameters:

ReceiverType – Callable with the signature void(SamplePtr<const FieldType>) noexcept

Parameters:

  • receiver – Callable with the appropriate signature. GetNewSamples will take ownership of this callable.

  • max_num_samples – Maximum number of samples to return via the given callable.

Returns:

Number of samples that were handed over to the callable or an error.

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<void> Subscribe(const std::size_t max_sample_count) noexcept#

Subscribe to the field.

Feature API:

Parameters:

max_sample_count – Specify the maximum number of concurrent samples that this event shall be able to offer to the using application.

Returns:

On failure, returns an error code.

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline void Unsubscribe() noexcept#

End subscription to a field and release needed resources.

Feature API:

It is illegal to call this method while data is still held by the application in the form of SamplePtr. Doing so will result in undefined behavior. After a call to this method, the field behaves as if it had just been constructed.

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline SubscriptionState GetSubscriptionState() noexcept#

Get the subscription state of this field.

Feature API:

This method can always be called regardless of the state of the field.

Returns:

Subscription state of the field.

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline std::size_t GetFreeSampleCount() noexcept#

Get the number of samples that can still be received by the user of this field.

Feature API:

If this returns 0, the user first has to drop at least one SamplePtr before it is possible to receive data via GetNewSamples again. If there is no subscription for this field, the returned value is unspecified.

Returns:

Number of samples that can still be received.

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<std::size_t> GetNumNewSamplesAvailable() noexcept#

Returns the number of new samples a call to GetNewSamples() (given parameter max_num_samples doesn’t restrict it) would currently provide.

Feature API:

This is a proprietary extension to the official ara::com API. It is useful in resource sensitive setups, where the user wants to work in polling mode only without registered async receive-handlers. For further details see //score/mw/com/design/extensions/README.md.

Returns:

Either 0 if no new samples are available (and GetNewSamples() wouldn’t return any) or N, where 1 <= N <= actual new samples. I.e. an implementation is allowed to report a lower number than actual new samples, which would be provided by a call to GetNewSamples().

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<void> SetReceiveHandler(EventReceiveHandler handler) noexcept#

Sets the handler to be called, whenever a new field value has been received.

Feature API:

Generally a ReceiveHandler has no restrictions on what mw::com API it is allowed to call. It is especially allowed to call all public APIs of the Field instance on which it had been set/registered as long as it obeys the general requirement, that API calls on a Proxy/Proxy field are thread safe/can’t be called concurrently.

Attention

This function MUST NOT be called from the context of a ReceiveHandler registered for this field! It makes semantically not really sense to register a “new” ReceiveHandler from the context of an already running ReceiveHandler. We also see no use cases for it and won’t support it therefore.

Parameters:

handler – user provided handler to be called

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<void> UnsetSubscriptionStateChangeHandler() noexcept#

Unsets/Unregisters a SubscriptionStateChangeHandler for this field. After this method returns, it is guaranteed, that the previously registered handler is neither active nor will be called anymore.

Feature API:

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<void> SetSubscriptionStateChangeHandler(SubscriptionStateChangeHandler handler) noexcept#

Sets/Registers a SubscriptionStateChangeHandler for this event. This handler will be called whenever the subscription state of this event changes.

Feature API:

Note

An already set/registered SubscriptionStateChangeHandler will be silently overridden.

Parameters:

handler –

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline Result<void> UnsetReceiveHandler() noexcept#

Removes any ReceiveHandler registered via SetReceiveHandler.

Feature API:

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithGetter, Tags...>::value>>
inline score::Result<MethodReturnTypePtr<T>> Get() noexcept#

Get the current value of the field.

Feature API:

This method is only available when the field is created with the WithGetter tag

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithSetter, Tags...>::value>>
inline score::Result<MethodReturnTypePtr<T>> Set(const SampleDataType &new_field_value) noexcept#

Set a new value to the field.

Feature API:

This method is only available when the field is created with the WithSetter tag

template<typename T = SampleDataType, typename = std::enable_if_t<is_tag_enabled<T, SampleDataType, WithNotifier, Tags...>::value>>
inline void InjectMock(IProxyEvent<FieldType> &proxy_event_mock)#
template<template<class> class Interface>
class ProxyWrapperClass : public Interface<ProxyTrait>#

Public Functions

inline ~ProxyWrapperClass()#
ProxyWrapperClass(const ProxyWrapperClass&) = delete#
ProxyWrapperClass &operator=(const ProxyWrapperClass&) = delete#
inline ProxyWrapperClass(ProxyWrapperClass &&other) noexcept#
inline ProxyWrapperClass &operator=(ProxyWrapperClass &&other) noexcept#

Public Static Functions

static inline Result<ProxyWrapperClass> Create(const HandleType instance_handle) noexcept#

Create a proxy instance from a service handle.

Feature API:

Exception-less proxy constructor that creates a proxy wrapper by creating the proxy binding for the given service handle and validating all service element bindings.

Parameters:

instance_handle – The handle identifying the service instance to connect to.

Returns:

On success, returns a ProxyWrapperClass instance. On failure, returns an error code.

template<typename T>
using score::mw::com::impl::ServiceHandleContainer = std::vector<T>#

The container holds a list of service handles and is used as a return value of the FindService methods. \requirement SWS_CM_00304.

Feature API:

Result<void> score::mw::com::impl::SkeletonBase::OfferService() noexcept#

Offer the respective service to other applications.

Feature API:

Returns:

On failure, returns an error code according to the SW Component Requirements SCR-17434118 and SCR-566325.

void score::mw::com::impl::SkeletonBase::StopOfferService() noexcept#

Stops offering the respective service to other applications \requirement SWS_CM_00111.

Feature API:

template<typename SampleDataType>
class SkeletonEvent : public score::mw::com::impl::SkeletonEventBase#

Public Types

using EventType = SampleDataType#

Public Functions

SkeletonEvent(SkeletonBase &skeleton_base, const std::string_view event_name)#

Constructor that should be called when instantiating a SkeletonEvent within a generated Skeleton. It should register itself with the skeleton on creation.

SkeletonEvent(SkeletonBase &skeleton_base, const std::string_view event_name, std::unique_ptr<SkeletonEventBinding<EventType>> binding, FieldOnlyConstructorEnabler)#

Constructor that should be called by a SkeletonField. This constructor does not register itself with the skeleton on creation.

We use FieldOnlyConstructorEnabler as an argument to prevent public usage of this constructor instead of using a private constructor to allow the constructor to be used with std::make_unique.

SkeletonEvent(SkeletonBase &skeleton_base, const std::string_view event_name, std::unique_ptr<SkeletonEventBinding<EventType>> binding)#

Constructor that allows to set the binding directly.

This is used only used for testing.

~SkeletonEvent() override = default#
SkeletonEvent(const SkeletonEvent&) = delete#
SkeletonEvent &operator=(const SkeletonEvent&) & = delete#
SkeletonEvent(SkeletonEvent &&other) noexcept = default#
SkeletonEvent &operator=(SkeletonEvent &&other) & noexcept = default#
Result<void> Send(const EventType &sample_value) noexcept#

Send event data to all subscribed clients.

Feature API:

EventType is allocated by the user and provided to the middleware to send. The data is copied by the middleware.

Parameters:

sample_value – The event data to be sent to subscribers.

Returns:

On failure, returns an error code.

Result<void> Send(SampleAllocateePtr<EventType> sample) noexcept#

Send event data using zero-copy mechanism.

Feature API:

EventType is previously allocated by middleware via Allocate() and provided by the user to indicate that filling the data is complete. This enables zero-copy transmission for better performance.

Parameters:

sample – The pre-allocated sample pointer containing the event data to be sent.

Returns:

On failure, returns an error code.

Result<SampleAllocateePtr<EventType>> Allocate() noexcept#

Allocates memory for EventType for the user to fill.

Feature API:

This is especially necessary for Zero-Copy implementations. The allocated memory can then be filled with data and sent using Send(SampleAllocateePtr).

Returns:

On success, returns a SampleAllocateePtr that can be filled with data. On failure, returns an error code.

inline void InjectMock(ISkeletonEvent<EventType> &skeleton_event_mock)#
template<typename SampleDataType, typename ...Tags>
class SkeletonFieldImpl : public score::mw::com::impl::SkeletonFieldBase#

Subclassed by score::mw::com::impl::SkeletonField< SampleType, Tags… >

Public Types

using FieldType = SampleDataType#

Public Functions

inline SkeletonFieldImpl(SkeletonBase &skeleton_base, const std::string_view field_name, std::unique_ptr<SkeletonEventBinding<FieldType>> binding)#

Testing ctor that delegates to the production ctor that accepts mock bindings directly, this can only be used in test code.

Parameters:

  • skeleton_base – Parent skeleton that owns this field’s registration.

  • field_name – Field’s name as it appears in the deployment.

  • binding – Mock event binding.

inline SkeletonFieldImpl(SkeletonBase &parent, const std::string_view field_name)#

Production ctor used by end users.

The MakeGetMethodIfEnabled / MakeSetMethodIfEnabled helpers consult the tag pack at compile time and return nullptr when their corresponding tag is absent.

Parameters:

  • parent – Parent skeleton that owns this field’s registration.

  • field_name – Field’s name as it appears in the deployment.

~SkeletonFieldImpl() override = default#
SkeletonFieldImpl(const SkeletonFieldImpl&) = delete#
SkeletonFieldImpl &operator=(const SkeletonFieldImpl&) & = delete#
SkeletonFieldImpl(SkeletonFieldImpl &&other) noexcept = default#
SkeletonFieldImpl &operator=(SkeletonFieldImpl &&other) & noexcept = default#
Result<void> Update(const FieldType &sample_value) noexcept#

FieldType is allocated by the user and provided to the middleware to send. Dispatches to SkeletonEvent::Send().

Feature API:

The initial value of the field must be set before PrepareOffer() is called. However, the actual value of the field cannot be set until the Skeleton has been set up via Skeleton::OfferService(). Therefore, we create a callback that will update the field value with sample_value which will be called in the first call to SkeletonFieldBase::PrepareOffer()

.

The initial value of the field must be set before

PrepareOffer() is called. However, the actual value of the field cannot be set until the Skeleton has been set up via Skeleton::OfferService(). Therefore, we create a callback that will update the field value with sample_value which will be called in the first call to SkeletonFieldBase::PrepareOffer().

Parameters:

sample_value – The field data to be sent to subscribers.

Returns:

On failure, returns an error code.

Result<void> Update(SampleAllocateePtr<FieldType> sample) noexcept#

FieldType is previously allocated by middleware and provided by the user to indicate that he is finished filling the provided pointer with live data. Dispatches to SkeletonEvent::Send().

Feature API:

Parameters:

sample – The pre-allocated sample pointer containing the field data to be sent.

Returns:

On failure, returns an error code.

Result<SampleAllocateePtr<FieldType>> Allocate() noexcept#

Allocates memory for FieldType for the user to fill it. This is especially necessary for Zero-Copy implementations. Dispatches to SkeletonEvent::Allocate().

Feature API:

This function cannot be currently called to set the initial value of a field as the shared memory must be first set up in the Skeleton::PrepareOffer() before the user can obtain / use a SampleAllocateePtr

.

This function cannot be currently called to set the initial value of a field as the shared memory must be first set up in the Skeleton::PrepareOffer() before the user can obtain / use a

SampleAllocateePtr.

Returns:

On success, returns a SampleAllocateePtr that can be filled with data. On failure, returns an error code.

inline void InjectMock(ISkeletonField<FieldType> &skeleton_field_mock)#
template<typename CallableType, typename U = SampleDataType, typename = std::enable_if_t<is_tag_enabled<U, SampleDataType, WithSetter, Tags...>::value>>
inline Result<void> RegisterSetHandler(CallableType &&user_set_handler)#

Registers a handler invoked by the middleware whenever a proxy calls the field setter.

Only available when the tag pack includes WithSetter (SFINAE-gated).

Template Parameters:

CallableType – Any callable (std::function, score::cpp::callback, lambda, …) with the signature void(FieldType& new_value), where new_value is the proxy-requested value at entry and the accepted value at exit.

Parameters:

handler – User callback to install.

Returns:

void on success otherwise the error code reported by the binding.

template<template<class> class Interface>
class SkeletonWrapperClass : public Interface<SkeletonTrait>#

Public Functions

inline ~SkeletonWrapperClass()#
SkeletonWrapperClass(const SkeletonWrapperClass&) = delete#
SkeletonWrapperClass &operator=(const SkeletonWrapperClass&) = delete#
inline SkeletonWrapperClass(SkeletonWrapperClass &&other) noexcept#
inline SkeletonWrapperClass &operator=(SkeletonWrapperClass &&other) noexcept#

Public Static Functions

static inline Result<SkeletonWrapperClass> Create(const InstanceSpecifier &specifier) noexcept#

Create a skeleton instance using an instance specifier.

Feature API:

Creates a skeleton wrapper by resolving the instance specifier to an instance identifier, then creating the skeleton binding and validating all service element bindings.

Parameters:

specifier – The instance specifier identifying the service instance.

Returns:

On success, returns a SkeletonWrapperClass instance. On failure, returns an error code.

static inline Result<SkeletonWrapperClass> Create(const InstanceIdentifier &instance_identifier) noexcept#

Create a skeleton instance using an instance identifier.

Feature API:

Creates a skeleton wrapper by creating the skeleton binding for the given instance identifier and validating all service element bindings.

Parameters:

instance_identifier – The instance identifier uniquely identifying the service instance.

Returns:

On success, returns a SkeletonWrapperClass instance. On failure, returns an error code.

enum class score::mw::com::impl::SubscriptionState : std::uint8_t#

state of a proxy event. \requirement SWS_CM_00310

Feature API:

Values:

enumerator kSubscribed#

kSubscribed is entered when the subscription has been successfully acknowledged by the provider side and the consumer has not been notified that the service is no longer offered (either the provider has called stop_offer() or crashed).

enumerator kNotSubscribed#

kNotSubscribed is entered when Subscribe() has not been called or the last successful Subscribe() has been withdrawn with call to Unsubscribe() Last call to Subscribe() has been rejected/negatively acknowledged by the provider side or provider side explicitly cancels an already acknowledged subscription.

enumerator kSubscriptionPending#

kSubscriptionPending state is entered when the Subscription() call is either in the state to being dispatched to the provider side or has been already dispatched to the provider side, but acknowlegde from provider side is pending state was already in kSubscribed, but then the consumer has been notified that the whole enclosing providing service instance has stopped offering. This is the “auto-reconnect mode”. As soon as the consumer is notified that the service instance is being offered again, the state would transition back to kSubscribed.

void score::mw::com::runtime::InitializeRuntime(const RuntimeConfiguration &runtime_configuration)#

Initializes mw::com subsystem with the given configuration.

Feature API:

This call is optional for a mw::com user. Only if the mw::com configuration (json) is not located in the default manifest path, this function shall be called when the caller already has the configuration path.

Attention

This function shall only be called ONCE per application/process lifetime! A second call may have no effect after an internal runtime singleton has been already created/is in use!

void score::mw::com::runtime::InitializeRuntime(const std::int32_t argc, score::StringLiteral argv[])#

Initializes mw::com subsystem with the given configuration referenced in the command-line options.

Feature API:

This call is optional for a mw::com user. Only if the mw::com configuration (json) is not located in the default manifest path, this function shall be called with the commandline option “-service_instance_manifest” pointing to the json config file to be used.

Attention

This function shall only be called ONCE per application/process lifetime! A second call may have no effect after an internal runtime singleton has been already created/is in use!

score::Result<InstanceIdentifierContainer> score::mw::com::runtime::ResolveInstanceIDs(const InstanceSpecifier model_name)#

Resolves given InstanceSpecifier (port name in the model) to a collection of InstanceIdentifiers via manifest lookup.

Feature API:

Parameters:

modelName – (name of the SWC port)

Returns:

container with InstanceIdentifiers \requirement SWS_CM_00118

Warning

doxygenfunction: Unable to resolve function “score::mw::com::runtime::RuntimeConfiguration::GetConfigurationPath” with arguments () const in doxygen xml output for project “doxygen_build” from directory: score/mw/com/design/doxygen_build/xml. Potential matches: 

- const filesystem::Path &GetConfigurationPath() const &
score::mw::com::runtime::RuntimeConfiguration::RuntimeConfiguration(const std::int32_t argc, score::StringLiteral argv[])

Constructor which initialiases the stored configuration path from command line arguments.

Feature API:

The constructor parses the command line arguments for a specific key to extract the configuration path. If the key is not found, a default path is used.

Parameters:

  • argc – The number of command line arguments.

  • argv – The array of command line arguments.

explicit score::mw::com::runtime::RuntimeConfiguration::RuntimeConfiguration(filesystem::Path configuration_path)

Constructor which initialiases the stored configuration path with the provided path.

Feature API:

Parameters:

configuration_path – The configuration path to be stored.

On this page
Show Source