класс <SI-Namespace>::proxy::fields::<Field>

Использование

Метод Get служит в области видимости прокси <SI-Namespace>::proxy::fields::<Field> для асинхронного запроса текущего значения поля ([SWS_CM_00112]; см. также AUTOSAR_AP_EXP_ARAComAPI §6 «FieldGet»). Функция предоставляется через заголовочный файл прокси <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h и существует только тогда, когда для поля смоделирован Field.hasGetter == TRUE ([SWS_CM_00112]). Она не принимает параметров и возвращает ara::core::Future<FieldType>, который после успешной передачи содержит текущее значение ([SWS_CM_00112]).

Обработка ошибок и граничные условия

Интерфейс определен как noexcept и безопасный к исключениям ([SWS_CM_00112]). В случае сбоя операции возвращаемый ara::core::Future содержит код ошибки с семантикой отката ([SWS_CM_00112]):

• ComErrc::kCommunicationFailure: сетевой биндинг сообщает об устранимой ошибке связи или о сбое защищенной связи ([SWS_CM_00112]).
• ComErrc::kMinimumSendIntervalViolationError: запрос на отправку поступил быстрее, чем позволяет сконфигурированный для элемента минимальный интервал отправки (minimumSendInterval) ([SWS_CM_00112]).
• InsufficientPermissionsViolation: выполнение отклонено механизмом контроля полномочий (Grant Enforcement) ([SWS_CM_00112]).

Ошибки приложения (Application Errors) для геттера отсутствуют ([SWS_CM_00113]).

Взаимодействие

На стороне скелетона обработка запроса геттера требует наличия обратного вызова, регистрируемого через RegisterGetHandler ([SWS_CM_00114]). Каждый вызов Get() выполняет сквозную проверку (E2E); полученный статус состояния можно синхронно запросить на стороне прокси через GetE2EStateMachineStateGetter ([SWS_CM_00145]).

Использование и контекст вызова

Функция Set предоставляется в пространстве имен <SI-Namespace>::proxy::fields::<Field> и доступна исключительно в том случае, если для поля настроено Field.hasSetter == TRUE [SWS_CM_00113]. Перед использованием экземпляр сервиса должен быть предложен на стороне сервера (OfferService()), а также найден и подключен на стороне клиента ARAComAPI §4.2 «Means of Communication». Вызов выполняется асинхронно: он передает новое значение поля через параметр value и возвращает ara::core::Future<FieldType> [SWS_CM_00113]. Метод специфицирован как noexcept и считается исключительнo безопасным [SWS_CM_00113].

Обработка ошибок

В случае сбоя передачи соответствующая ошибка предоставляется через возвращенный ara::core::Future [SWS_CM_00113]:

• ComErrc::kCommunicationFailure: сообщает об устранимой ошибке связи или о нарушении безопасной передачи; в случае таймаута на стороне сервера возможно неопределенное состояние без семантики отката (rollback) [SWS_CM_00113].
• ComErrc::kMinimumSendIntervalViolationError: возникает, если запрос на отправку был отправлен быстрее, чем сконфигурированный минимальный интервал отправки (minimumSendInterval) (также без семантики отката) [SWS_CM_00113].
• Отсутствие прав доступа приводит к отклонению со стороны механизма Grant Enforcement (InsufficientPermissionsViolation) [SWS_CM_00113].
• Ошибки приложения передаются не через исключения, а путем возврата значения, отличного от параметра запроса, в случае успешного завершения future [SWS_CM_00113].

Взаимодействие и параллелизм

На стороне сервера вызов соответствует колбэку на экземпляре скелетона, который предварительно должен быть зарегистрирован с помощью RegisterSetHandler [SWS_CM_00116] ARAComAPI §4.2 «Means of Communication». Для мониторинга безопасности передачи E2E на стороне клиента статус конечного автомата E2E последнего вызова Set() можно запросить через GetE2EStateMachineStateSetter() [SWS_CM_00146].

Использование и контекст вызова

Функция SetReceiveHandler предоставляется на стороне прокси в пространстве имен <SI-Namespace>::proxy::fields::<Field> через заголовочный файл <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h ([SWS_CM_11605]). Она регистрирует на стороне клиента обратный вызов для уведомлений при изменениях значения поля ([SWS_CM_11605]). Этот механизм следует процедуре уведомлений событий, благодаря чему Communication Management информирует клиента при обновлениях (EXP_ARAComAPI §4.2 «Means of Communication»).

В качестве параметра передается ara::com::FieldReceiveHandler, представляющий собой функцию без параметров ([SWS_CM_11605]). Функция не возвращает значения (void) и специфицирована как безопасная относительно исключений (noexcept) ([SWS_CM_11605]).

Обработка ошибок и параллелизм

Если переданный вызываемый объект не существует или равен null, функция сообщает о нарушении InvalidHandlerViolation ([SWS_CM_11605]). Если выполнение обработчика должно осуществляться в определенном контексте выполнения, доступен шаблонный вариант с ExecutorT ([SWS_CM_11611]).

Взаимодействие

Поведение соответствует регистрации обработчиков для событий ([SWS_CM_00181]) и триггеров ([SWS_CM_00250]). Отмена регистрации, вероятно, выполняется через UnsetReceiveHandler() в соответствии с шаблоном интерфейса класса прокси (EXP_ARAComAPI §5.3.1 «Proxy Class API’s»). Вопрос Q-74cd83b99aadec16 (открытый)

Использование и контекст вызова

Шаблонная функция SetReceiveHandler является частью класса прокси class <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11611]; заголовочный файл #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h"). Она служит для регистрации на стороне клиента обработчика приема для уведомлений при изменениях значения поля (AUTOSAR_AP_EXP_ARAComAPI §4.2 «Means of Communication», [SWS_CM_11605]). Через параметры передаются вызываемый объект handler типа ara::com::FieldReceiveHandler, а также контекст выполнения executor в виде универсальной ссылки ExecutorT&& ([SWS_CM_11611]). Функция не имеет возвращаемого значения (void).

Обработка ошибок и безопасность исключений

Метод объявлен как noexcept и специфицирован как безопасный относительно исключений (exception safe) ([SWS_CM_11611]). Если переданный вызываемый объект handler не существует или равен null, имеет место InvalidHandlerViolation ([SWS_CM_11611]). Поэтому вызывающие стороны должны гарантировать предоставление валидной функции или функционального объекта перед вызовом.

Параллелизм и взаимодействие

В отличие от стандартной регистрации без исполнителя ([SWS_CM_11605]), при поступлении уведомления поля обратный вызов обрабатывается в контексте выполнения, предоставленном executor ([SWS_CM_11611]). Интерпретация: это, вероятно, обеспечивает разделение, предотвращая выполнение специфической для приложения обработки данных в контекстах выполнения внутренних потоков промежуточного программного обеспечения. Вопрос Q-cbe1af19bea15a88 (открытый) Метод относится к API классов прокси (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s») и следует тому же шаблону, что и варианты с исполнителем для событий ([SWS_CM_11356] на основе [SWS_CM_00181]), а также триггеров ([SWS_CM_00352] на основе [SWS_CM_00250]).

Функция SetSubscriptionStateChangeHandler регистрирует на поле прокси (область видимости <SI-Namespace>::proxy::fields::<Field>) пользовательский callback, вызываемый Communication Management, как только изменяется состояние подписки (ara::com::SubscriptionState) поля ([SWS_CM_11607], [SWS_CM_00333]). Вызов выполняется синхронно и не возвращает значения ([SWS_CM_11607]). Она относится к центральным интерфейсам прокси для управления подписками на события и поля (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s»).

В отношении обработки ошибок функция регистрации специфицирована как exception safe и объявлена с noexcept ([SWS_CM_11607]). Если переданный вызываемый объект handler не существует или равен null, имеет место нарушение спецификации в форме InvalidHandlerViolation ([SWS_CM_11607]).

При взаимодействии с установлением соединения следует учитывать, что Subscribe() в принципе должна рассматриваться как асинхронная операция ([SWS_CM_12006]). Поэтому даже после безошибочного возврата из Subscribe() приложения могут исходить из успешной подписки только тогда, когда зарегистрированный обработчик просигнализировал состояние kSubscribed ([SWS_CM_12006]). Кроме того, Communication Management вызывает обработчик с kSubscriptionPending, если фактическое связывание не может быть завершено немедленно или экземпляр сервера выходит из строя, например, вследствие перезапуска или сетевой ошибки ([SWS_CM_00313]). Если обработчик должен выполняться в определенном контексте выполнения, для этого доступен перегруженный шаблонный вариант с ExecutorT ([SWS_CM_11608]).

Шаблонная функция SetSubscriptionStateChangeHandler в пространстве имен <SI-Namespace>::proxy::fields::<Field> служит для регистрации функции обратного вызова для отслеживания изменений состояния подписки на поле ([SWS_CM_11608]). Она расширяет базовое поведение из [SWS_CM_11607] тем, что зарегистрированный обработчик выполняется в явно переданном контексте выполнения (executor) ([SWS_CM_11608]).

Метод принимает два параметра ([SWS_CM_11608]):

• handler: вызываемый обратный вызов типа ara::com::SubscriptionStateChangeHandler ([SWS_CM_11354]), который инициируется, как только изменяется ara::com::SubscriptionState ([SWS_CM_00333]).
• executor: прямая ссылка (forwarding reference) типа ExecutorT&& ([SWS_CM_11360]), предоставляющая контекст для выполнения обработчика ([SWS_CM_11608]).

Функция не возвращает значения (void) и объявлена как noexcept ([SWS_CM_11608]). Она специфицирована как exception safe ([SWS_CM_11608]). В качестве нарушения определено InvalidHandlerViolation на случай, если переданный вызываемый объект не существует или равен null ([SWS_CM_11608]).

Интерпретация: благодаря передаче executor выполнение обработчика, вероятно, переносится из внутреннего контекста управления коммуникациями в контекст потока или задач приложения. Вопрос Q-647f618545799c4e (открытый) Во взаимодействии API прокси этот вызов встает в один ряд с такими методами, как Subscribe(), Unsubscribe() и UnsetSubscriptionStateChangeHandler() (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s»). Аналогичные перегруженные варианты с контекстом выполнения существуют для событий прокси ([SWS_CM_11354]) и триггеров прокси ([SWS_CM_01106]).

Использование и контекст вызова

Функция-член SetTransportFaultConditionHandler служит для регистрации обработчика ошибок для нотификатора поля Proxy в пространстве имен <SI-Namespace>::proxy::fields::<Field> [SWS_CM_00109]. В качестве параметра передается вызываемый объект (Callable) типа ara::com::e2e::TransportFaultConditionHandler. Функция не возвращает значения и связывает обратный вызов с нотификаторами отдельных экземпляров сервисов для приема ошибок передачи от коммуникационного бэкенда AUTOSAR_AP_SWS_CommunicationManagement §7.4 «End-to-end communication protection» с. 235.

Обработка ошибок и безопасность исключений

Метод объявлен как noexcept и специфицирован как исключениебезопасный (exception safe) [SWS_CM_00109]. Если переданный callable-объект недействителен или равен null, имеет место нарушение предусловия в форме InvalidHandlerViolation [SWS_CM_00109]. Интерпретация: поскольку функция не должна выбрасывать исключения, такое нарушение в AUTOSAR Adaptive, как правило, приводит к немедленному аварийному завершению программы. Вопрос Q-74df6934d4ae3c93 (открытый)

Параллелизм и взаимодействие

В то время как эта базовая форма регистрирует обработчик напрямую, в виде [SWS_CM_00110] существует перегруженный шаблонный вариант, который дополнительно принимает Executor (ExecutorT&& executor) для задания контекста асинхронного выполнения. Функция встраивается в сквозную обработку ошибок: в то время как нотификаторы ([SWS_CM_00109], [SWS_CM_00110]), события ([SWS_CM_00099]) и триггеры ([SWS_CM_00106]) сообщают об ошибках передачи асинхронно через такие обработчики, транспортные ошибки при запросах методов, а также геттеров и сеттеров возвращаются через ComErrc::kCommunicationFailure в результирующем ara::core::Future [SWS_CM_00090].

Использование

Шаблонная функция-член SetTransportFaultConditionHandler служит в области видимости класса поля прокси (<SI-Namespace>::proxy::fields::<Field>) для регистрации обработчика для уведомителя соответствующего поля [SWS_CM_00110]. Она принимает два входных параметра:

• handler: регистрируемый вызываемый объект типа ara::com::e2e::TransportFaultConditionHandler [SWS_CM_00110].
• executor: rvalue-ссылка на объект исполнителя (ExecutorT&&), в контексте выполнения которого запускаются любые асинхронно инициированные вычисления [SWS_CM_00110].

Функция не возвращает значения (void) и объявлена как noexcept [SWS_CM_00110].

Обработка ошибок и безопасность выполнения

Интерфейс специфицирован как исключение-безопасный (exception safe) [SWS_CM_00110]. Если в качестве handler передан несуществующий или равный null вызываемый объект, это приводит к InvalidHandlerViolation [SWS_CM_00110]. Через этот обработчик сообщается об особых условиях транспортных ошибок, тогда как методы, а также геттеры и сеттеры полей сигнализируют о любых транспортных ошибках через ComErrc::kCommunicationFailure в своих соответствующих возвращаемых Future [SWS_CM_00090].

Параллелизм и взаимодействие

Метод представляет собой перегрузку с контекстом выполнения для базовой функции с меньшим числом параметров [SWS_CM_00109]. Благодаря переданному объекту исполнителя реализация отделяет выполнение обработчика от внутреннего контекста приёма Communication Management [SWS_CM_00110]. Аналогичные перегрузки доступны для событий прокси [SWS_CM_00100], триггеров прокси [SWS_CM_00107], а также для методов скелетона [SWS_CM_00094] и полей скелетона [SWS_CM_00097]. Интерпретация: вызов целесообразно выполнять до поступления сообщений уведомителя или подписки на уведомитель, чтобы обеспечить непрерывный мониторинг ошибок. Вопрос Q-bc5c62dd39c09029 (открытый)

Метод Subscribe служит для подписки на уведомления для Field экземпляра прокси сервиса в области видимости proxy::fields::<Field> ([SWS_CM_11601]). Через параметр maxSampleCount приложение задает максимальное количество сэмплов данных, которые оно хочет удерживать одновременно, и тем самым настраивает локальный кэш приема ([SWS_CM_11601], EXP ARAComAPI §5.3 «Proxy Class API’s»). Вызов является асинхронным: возвращаемый ara::core::Result<void> сигнализирует лишь о принятии подписки со стороны Communication Management (EXP ARAComAPI §5.3.5.2 «Monitoring Event Subscription»).

В отношении поведения состояний и обработки ошибок действуют следующие правила:

• Идемпотентность: если Field уже находится в состоянии kSubscribed или kSubscriptionPending и переданный maxSampleCount совпадает со значением текущей подписки, метод возвращает управление без выполнения действий ([SWS_CM_11601]).
• Коды ошибок: если требуемый кэш не может быть предоставлен, операция завершается с ошибкой ComErrc::kMaxSampleCountNotRealizable ([SWS_CM_11601], [SWS_CM_10432]).
• Проверка полномочий: при отсутствии необходимых прав вызов отклоняется механизмом Grant Enforcement с ошибкой InsufficientPermissionsViolation ([SWS_CM_11601]).

Метод объявлен как noexcept и специфицирован как Exception-safe ([SWS_CM_11601]). Семантически он следует поведению подписки на события ([SWS_CM_00141]); сконфигурированный кэш формирует основу для последующего приема сэмплов через такие методы, как GetNewSamples ([SWS_CM_00701]).

Функция UnsetReceiveHandler() служит на уровне прокси для дерегистрации ранее зарегистрированного обработчика приема для уведомлений поля ([SWS_CM_11606]). Она относится к API классов прокси ara::com (AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s») и располагается в пространстве имен <SI-Namespace>::proxy::fields::<Field> ([SWS_CM_11606]).

Что касается контекста вызова и семантики, метод не принимает параметров и не возвращает значения ([SWS_CM_11606]). С помощью этого вызова приложение может в любой момент переключиться с событийно-управляемой модели уведомлений на работу в режиме опроса (polling), отозвав пользовательский обратный вызов (AUTOSAR_AP_EXP_ARAComAPI §5.3.2 «RadarService Proxy Class Example»).

Для обработки ошибок функция специфицирована как noexcept, а также exception safe ([SWS_CM_11606]); специфические коды ошибок согласно спецификации отсутствуют. Вызов выполняется синхронно; после успешного отзыва обработчика Communication Management больше не инициирует вызовы callback при поступлении новых данных (интерпретация: выполняющиеся в данный момент или уже запланированные запуски, вероятно, завершаются или обрабатываются сериализованно до отзыва, поскольку вызовы callback со стороны Communication Management должны выполняться сериализованно; ср. AUTOSAR_AP_EXP_ARAComAPI §5.3.2 «RadarService Proxy Class Example»). Вопрос Q-fbc65e80b8d8be38 (открытый)

При взаимодействии метод соответствует отключению триггеров при событиях сервиса ([SWS_CM_00183]; AUTOSAR_AP_EXP_ARAComAPI §10) и триггерах ([SWS_CM_11614]). В связывании DDS (DDS-Binding) поведение отображается через сопоставление UnsetReceiveHandler() с соответствующим DataReader ([SWS_CM_11141]).

Использование

Метод UnsetSubscriptionStateChangeHandler служит в рамках платформы AUTOSAR Adaptive для удаления ранее зарегистрированного обратного вызова для изменений состояния подписки (ara::com::SubscriptionState) поля [SWS_CM_11609]. Он вызывается синхронно на экземплярах полей прокси сервиса в пространстве имен <SI-Namespace>::proxy::fields::<Field> и требует подключения сгенерированного заголовочного файла #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 «UnsetSubscriptionStateChangeHandler». Вызов не принимает входных параметров и не возвращает значения.

Обработка ошибок и параллелизм

Интерфейс объявлен как noexcept и, согласно спецификации, удовлетворяет свойству exception safe [SWS_CM_11609]. Возникновение ошибок или исключений тем самым исключено. Поскольку отмена регистрации вступает в силу немедленно, следует исходить из того (интерпретация), что после завершения метода новые уведомления прежнему обработчику передаваться больше не будут. Вопрос Q-30238329b76b64f4 (открытый)

Взаимодействие

Функция относится к базовым API классов прокси для управления подписками в ara::com AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s». Аналогичные методы деактивации обработчиков изменений состояния существуют для событий [SWS_CM_00334] и триггеров [SWS_CM_01108] прокси, а также зеркально на стороне скелетона для событий [SWS_CM_12010] и триггеров [SWS_CM_01112].

Использование

Функция UnsetTransportFaultConditionHandler служит для отмены регистрации ранее зарегистрированного ara::com::e2e::TransportFaultConditionHandler для notifier определенного поля прокси [SWS_CM_00126]. Она определена в области видимости <SI-Namespace>::proxy::fields::<Field> и подключается через заголовочный файл <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.1.4 «UnsetTransportFaultConditionHandler». Вызов выполняется без параметров и не возвращает значения (void).

Обработка ошибок

Метод объявлен как noexcept и обладает гарантией безопасности исключений exception safe [SWS_CM_00126]. Коды ошибок не возвращаются, и исключения не генерируются. Если обработчик не был зарегистрирован ранее, повторный вызов, по-видимому, не окажет никакого эффекта. Вопрос Q-85da9a7b00678748 (открытый)

Параллелизм и ограничения

Спецификация не определяет отдельных требований к параллелизму или потокобезопасности. Поскольку интерфейс работает синхронно и не использует асинхронные типы, отмена обработчика ошибок, вероятно, вступает в силу синхронно и незамедлительно. Вопрос Q-ed4cc712bb55aee5 (открытый) Вызывающим сторонам следует координировать вызов в жизненном цикле приложения таким образом, чтобы сообщения notifier отдельных экземпляров сервиса не обрабатывались бесконтрольно без обработчика AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 «End-to-end communication protection for SOMEIP».

Взаимодействие

Отмена регистрации следует согласованному шаблону именования и функций в AUTOSAR Adaptive:

• На уровне прокси доступны эквивалентные функции для событий ([SWS_CM_00105]), а также для триггеров ([SWS_CM_00108]).
• На уровне скелетона существуют соответствующие аналоги для геттеров и сеттеров полей ([SWS_CM_00098]), а также в целом для всех методов интерфейса скелетона ([SWS_CM_00095]).