clase ara::diag::FileTransferService

El método DeleteFile de la clase ara::diag::FileTransferService (SWS Diagnostics §8.18.1.2.3.1 «DeleteFile», encabezado #include "ara/diag/file_transfer.h") gestiona el proceso completo de eliminación de un archivo en el marco del servicio UDS RequestFileTransfer (0x38) con el modo DeleteFile [SWS_DM_01335]. El servicio UDS se proporciona en el lado del servidor de conformidad con ISO 14229-1 [SWS_DM_01310] SWS Diagnostics §7.3.2.8.20 «Service 0x38 – RequestFileTransfer».

En la llamada se pasan tres parámetros [SWS_DM_01335]:

• fileName (ara::core::String): indicación de ruta y nombre del archivo de destino (interpretación: a pesar de la indicación editorial «file to read» en el texto de la especificación, se trata del archivo que se va a eliminar). Pregunta Q-cdbe1185bb030e87 (abierta)
• metaInfo (MetaInfo const &): metainformación de la solicitud de diagnóstico actual.
• cancellationHandler (CancellationHandler): permite comprobar el estado de cancelación a través de cancellationHandler.IsCanceled(), así como registrar una función de notificación a través de cancellationHandler.SetNotifier() en caso de que la conversación en curso se cancele.

Como resultado asíncrono, la función devuelve un ara::core::Future<void> [SWS_DM_01335]. Una finalización exitosa señala al cliente de diagnóstico un comportamiento de respuesta positivo. En caso de error, debe proporcionarse un NRC de UDS pertinente según ISO 14229-1 a través de DiagUdsNrcErrc en el Future [SWS_DM_01335].

La función está especificada como noexcept y se considera segura frente a excepciones («exception safe») [SWS_DM_01335]. El requisito de seguridad para subprocesos es condicional y se controla mediante el ConcurrencyType pasado al constructor [SWS_DM_01335].

usar

El método Offer de la clase ara::diag::FileTransferService registra el gestor ante Diagnostic Management (DM), de modo que este pueda reenviar solicitudes de diagnóstico entrantes para la transferencia de archivos a la instancia [SWS_DM_01336]. La llamada se realiza sin parámetros y de forma síncrona. El tipo de retorno es ara::core::Result<void>, mediante el cual se señala el éxito del registro o un error ocurrido [SWS_DM_01336].

Manejo de errores

Si se produce un error durante la provisión, la función devuelve un ara::core::Result erróneo. En caso de que el servicio ya se hubiera ofrecido con éxito previamente para la instancia en cuestión, se devuelve el código de error específico DiagOfferErrc::kAlreadyOffered con semántica de reversión [SWS_DM_01336].

Concurrencia y restricciones

La función está declarada como segura frente a excepciones (exception safe) y noexcept, pero se considera no segura para subprocesos (not thread-safe) [SWS_DM_01336]. Por lo tanto, las llamadas sobre la misma instancia de servicio no deben ejecutarse en paralelo desde múltiples subprocesos sin protección.

Interacción

El ofrecimiento a través de Offer se corresponde con el patrón de provisión estandarizado para gestores de diagnóstico en Adaptive AUTOSAR. Existen mecanismos análogos para el reenvío de solicitudes por parte del DM, por ejemplo para la descarga de archivos [SWS_DM_00792], la subida [SWS_DM_00802] y servicios generales de UDS [SWS_DM_00619].

El método ara::diag::FileTransferService::RequestReadDirectory es invocado por la instancia del Diagnostic Server cuando se recibe una solicitud de diagnóstico para RequestFileTransfer (0x38) con el modeOfOperation ReadDir (0x05) [SWS_DM_01315]. La función toma los siguientes parámetros [SWS_DM_01332]:

• directoryName: ruta que incluye el nombre del directorio que se va a leer.
• metaInfo: metainformación de la solicitud de diagnóstico entrante.
• cancellationHandler: objeto para consultar la cancelación de una conversación mediante cancellationHandler.IsCanceled() o para registrar una función de callback mediante cancellationHandler.SetNotifier() para eventos de cancelación.

El retorno se realiza de forma asíncrona mediante un ara::core::Future<std::tuple<DataTransferReadSession, std::uint64_t>> [SWS_DM_01332]. En caso de éxito, la tupla contiene la estrategia de acceso DataTransferReadSession, así como el tamaño del directorio que se transmitirá al cliente UDS [SWS_DM_01332]. El objeto DataTransferReadSession establece así la conexión entre la inicialización mediante RequestFileTransfer (0x38) y las posteriores transferencias de archivos a través de TransferData (0x36) SWS Diagnostics p. 184 «Realization of modeOfOperation ReadDir (0x05)».

Si el procesamiento falla, el Future devuelve un código de respuesta negativo (NRC) conforme a ISO 14229-1 a través de DiagUdsNrcErrc [SWS_DM_01332]. El método está especificado como noexcept y seguro frente a excepciones (exception safe) [SWS_DM_01332]. La seguridad para subprocesos es condicional: si la función debe implementarse como segura para subprocesos se determina mediante el ConcurrencyType pasado en el constructor [SWS_DM_01332].

usar

La instancia del Diagnostic Server llama al método RequestReadFile tan pronto como se recibe una solicitud de diagnóstico para RequestFileTransfer (0x38) con el modo de operación ReadFile (0x04) [SWS_DM_01314]. La función toma la ruta del archivo junto con su nombre (fileName), el formato de datos (dataFormatIdentifier), metadatos de la solicitud (metaInfo), así como un cancellationHandler [SWS_DM_01331]. A través de cancellationHandler se puede consultar el estado de cancelación (IsCanceled) o registrar una función de notificación para la cancelación de la conversación actual (SetNotifier) [SWS_DM_01331].

La ejecución se realiza de forma asíncrona y devuelve un ara::core::Future. En caso de éxito, el future proporciona una tupla compuesta por DataTransferReadSession y FileSizes [SWS_DM_01331]. En FileSizes, un valor de 0 para uncompressed_size o compressed_size señala que el tamaño respectivo no se transmitirá al cliente UDS; para archivos no comprimidos, compressed_size debe establecerse en cero [SWS_DM_01331].

Manejo de errores

Si la preparación del proceso de lectura falla, la aplicación notifica un NRC de UDS adecuado según ISO 14229-1 a través de DiagUdsNrcErrc en el future devuelto [SWS_DM_01331].

Concurrencia e interacción

La función está declarada como noexcept. La seguridad para subprocesos es condicional (conditional): el ConcurrencyType pasado al constructor decide si la implementación debe diseñarse como segura para subprocesos [SWS_DM_01331]. El objeto DataTransferReadSession devuelto constituye el enlace entre el procesamiento de RequestFileTransfer y los servicios TransferData subsiguientes (0x36), a través de los cuales se transmite el flujo de datos del archivo propiamente dicho SWS Diagnostics p. 184.

El método RequestResumeWriteFile es invocado por una instancia del Diagnostic Server cuando se recibe una solicitud de servicio UDS para RequestFileTransfer (0x38) con el modo de funcionamiento ResumeFile (0x06) ([SWS_DM_01316], SWS Diagnostics §[SWS_DM_01316] «Realization of modeOfOperation ResumeFile (0x06)»). Su propósito es reanudar un proceso de escritura previamente interrumpido para un archivo.

En la llamada se transmiten la ruta del archivo (fileName), el identificador de formato de datos UDS (dataFormatIdentifier), los tamaños de archivo (fileSizes), metadatos de la solicitud (metaInfo), así como un cancellationHandler ([SWS_DM_01334], SWS Diagnostics §8.18.1.2.3.5 «RequestResumeWriteFile»). A través de cancellationHandler, la aplicación puede verificar activamente mediante IsCanceled si la conversación de diagnóstico en curso ha sido cancelada, o registrar una función de notificación para una cancelación mediante SetNotifier ([SWS_DM_01334]).

El retorno se realiza de forma asíncrona mediante ara::core::Future<std::tuple<DataTransferWriteSession, std::uint64_t>> ([SWS_DM_01334]). En caso de éxito, el future proporciona una tupla que contiene una instancia de DataTransferWriteSession así como la posición en bytes a partir de la cual debe continuarse la transferencia ([SWS_DM_01334]). Este objeto de sesión vincula la inicialización mediante RequestFileTransfer con los servicios TransferData posteriores (0x36) (SWS Diagnostics §[SWS_DM_01316] «Realization of modeOfOperation ResumeFile (0x06)»).

En caso de error, el future debe completarse con un NRC de UDS apropiado según ISO 14229-1 a través de DiagUdsNrcErrc ([SWS_DM_01334]). La función está declarada como noexcept y es segura frente a excepciones; la seguridad para subprocesos es condicional («conditional») y viene determinada por el ConcurrencyType pasado en el constructor ([SWS_DM_01334]).

usar

El servidor de diagnóstico llama al método [SWS_DM_01333] en cuanto se recibe una solicitud de servicio UDS RequestFileTransfer (0x38) con el modo de funcionamiento WriteFile ([SWS_DM_01310]). Si la solicitud se transmite con el modo de funcionamiento ReplaceFile (0x03), el servidor de diagnóstico invoca la interfaz con el modo de escritura kReplace ([SWS_DM_01313]). La llamada pasa el nombre del archivo (fileName), el identificador del formato de datos (dataFormatIdentifier), tamaños de archivo (fileSizes), el modo de reemplazo (mode), metadatos adicionales (metaInfo), así como un cancellationHandler. La indicación «file to read» de la especificación en el parámetro fileName probablemente sea un descuido editorial y designa la ruta de destino del archivo que se va a escribir. Pregunta Q-f14158fc20fda8af (abierta)

El procesamiento se realiza de forma asíncrona y devuelve un ara::core::Future<DataTransferWriteSession> ([SWS_DM_01333]). La sesión resultante sirve como enlace entre la inicialización a través del servicio 0x38 y las posteriores transferencias de datos mediante TransferData (0x36) (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.20 «Service 0x38 – RequestFileTransfer»).

Tratamiento de errores y concurrencia

El método está declarado como noexcept. Si se produce un error, no se lanza ningún error de C++, sino que se devuelve un NRC de UDS apropiado de DiagUdsNrcErrc según ISO 14229-1 en el future ([SWS_DM_01333]). A través del cancellationHandler pasado, se puede consultar el estado de cancelación mediante IsCanceled() o registrar una notificación con SetNotifier() en caso de que la conversación de diagnóstico se interrumpa. La seguridad para subprocesos es condicional: si la función debe implementarse como segura para subprocesos se determina mediante el ConcurrencyType en el constructor ([SWS_DM_01333]).

Interacción

La operación complementa la interacción de los servicios de transferencia de archivos y es complementaria a operaciones de lectura como RequestReadFile ([SWS_DM_01314]) o a la reanudación de procesos de escritura interrumpidos a través de RequestResumeWriteFile ([SWS_DM_01316]).

La función StopOffer de la clase ara::diag::FileTransferService sirve para dar de baja el servicio frente a Diagnostic Management ([SWS_DM_01337]; AUTOSAR_AP_SWS_Diagnostics §8.18.1.2.3.7 «StopOffer»). Su llamada hace que el DM deje de reenviar solicitudes de diagnóstico entrantes a esta instancia de servicio a partir de ese momento. La interfaz está definida en el encabezado #include "ara/diag/file_transfer.h", posee la firma void StopOffer() const noexcept;, no espera parámetros y no proporciona valor de retorno. La llamada se ejecuta de forma síncrona.

Para StopOffer no se prevé ningún mecanismo de error. El método está declarado como seguro frente a excepciones (exception safe) y con el identificador noexcept ([SWS_DM_01337]). No se lanzan excepciones ni se devuelven códigos de error a la aplicación. La desactivación del reenvío no falla desde el punto de vista de la API.

Según la especificación, StopOffer está clasificado como no seguro para subprocesos (not thread-safe) ([SWS_DM_01337]). Por lo tanto, los accesos paralelos a la misma instancia de ara::diag::FileTransferService deben protegerse contra la concurrencia del lado de la aplicación. Interpretación: la desactivación probablemente se realice típicamente antes de la destrucción del objeto o durante una parada ordenada de la aplicación de procesamiento, con el fin de evitar que lleguen solicitudes a una rutina que ya no esté operativa. Pregunta Q-e7bb2a5621c39160 (abierta)

La desactivación mediante StopOffer sigue el patrón arquitectónico uniforme de AUTOSAR Adaptive para servicios de diagnóstico provistos. Se corresponde con funciones de desactivación análogas de clases relacionadas como ara::diag::DownloadService ([SWS_DM_00793]), ara::diag::UploadService ([SWS_DM_00803]), ara::diag::CommunicationControl ([SWS_DM_00810]) y ara::diag::Monitor ([SWS_DM_01089]; AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 «Monitors»).