classe ara::diag::FileTransferService

O método DeleteFile da classe ara::diag::FileTransferService (SWS Diagnostics §8.18.1.2.3.1 «DeleteFile», cabeçalho #include "ara/diag/file_transfer.h") processa o procedimento completo de eliminação de um ficheiro no âmbito do serviço UDS RequestFileTransfer (0x38) com o modo DeleteFile [SWS_DM_01335]. O serviço UDS é disponibilizado do lado do servidor em conformidade com a ISO 14229-1 [SWS_DM_01310] SWS Diagnostics §7.3.2.8.20 «Service 0x38 – RequestFileTransfer».

Aquando da chamada, são passados três parâmetros [SWS_DM_01335]:

• fileName (ara::core::String): indicação do caminho e nome do ficheiro de destino (interpretação: apesar da indicação editorial «file to read» no texto da especificação, trata-se do ficheiro a eliminar). Pergunta Q-cdbe1185bb030e87 (aberta)
• metaInfo (MetaInfo const &): metainformações do pedido de diagnóstico atual.
• cancellationHandler (CancellationHandler): permite verificar o estado de cancelamento via cancellationHandler.IsCanceled(), bem como registar uma função de notificação através de cancellationHandler.SetNotifier(), caso a conversação em curso seja cancelada.

Como resultado assíncrono, a função devolve um ara::core::Future<void> [SWS_DM_01335]. Uma conclusão bem-sucedida sinaliza ao cliente de diagnóstico um comportamento de resposta positiva. Em caso de erro, deve ser disponibilizado no Future um UDS-NRC aplicável em conformidade com a ISO 14229-1 através de DiagUdsNrcErrc [SWS_DM_01335].

A função está especificada como noexcept e é considerada segura em termos de exceções («exception safe») [SWS_DM_01335]. O requisito de segurança entre threads é condicional e é controlado através do ConcurrencyType passado ao construtor [SWS_DM_01335].

usar

O método Offer da classe ara::diag::FileTransferService regista o manipulador no Diagnostic Management (DM), para que este possa encaminhar pedidos de diagnóstico recebidos para transferência de ficheiros para a instância [SWS_DM_01336]. A chamada é efetuada sem parâmetros e de forma síncrona. O tipo de retorno é ara::core::Result<void>, sinalizando o sucesso do registo ou um erro ocorrido [SWS_DM_01336].

Tratamento de erros

Se ocorrer um erro aquando da disponibilização, a função fornece um ara::core::Result com erro. Caso o serviço já tenha sido oferecido anteriormente com sucesso para a instância em causa, é devolvido o código de erro específico DiagOfferErrc::kAlreadyOffered com semântica de rollback [SWS_DM_01336].

Simultaneidade e restrições

A função está declarada como segura em termos de exceções (exception safe) e noexcept, mas é considerada não segura entre threads (not thread-safe) [SWS_DM_01336]. As chamadas na mesma instância de serviço não podem, por isso, ser executadas em paralelo a partir de múltiplas threads sem proteção.

Interação

A oferta através de Offer corresponde ao padrão de disponibilização normalizado para manipuladores de diagnóstico no Adaptive AUTOSAR. Existem mecanismos análogos para o encaminhamento de pedidos pelo DM, por exemplo, para o download de ficheiros [SWS_DM_00792], o upload [SWS_DM_00802], bem como serviços UDS gerais [SWS_DM_00619].

O método ara::diag::FileTransferService::RequestReadDirectory é chamado pela instância do Diagnostic Server quando é recebido um pedido de diagnóstico para RequestFileTransfer (0x38) com o modeOfOperation ReadDir (0x05) [SWS_DM_01315]. A função aceita os seguintes parâmetros [SWS_DM_01332]:

• directoryName: caminho, incluindo o nome do diretório, do diretório a ler.
• metaInfo: metainformações do pedido de diagnóstico recebido.
• cancellationHandler: objeto para consultar o cancelamento da conversação através de cancellationHandler.IsCanceled() ou para registar uma função de callback através de cancellationHandler.SetNotifier() para eventos de cancelamento.

O retorno ocorre de forma assíncrona através de um ara::core::Future<std::tuple<DataTransferReadSession, std::uint64_t>> [SWS_DM_01332]. Em caso de sucesso, o tuplo contém a estratégia de acesso DataTransferReadSession, bem como o tamanho do diretório que é transmitido ao cliente UDS [SWS_DM_01332]. O objeto DataTransferReadSession estabelece a ligação entre a inicialização por RequestFileTransfer (0x38) e as subsequentes transferências de ficheiros através de TransferData (0x36) SWS Diagnostics p. 184 «Realization of modeOfOperation ReadDir (0x05)».

Se o processamento falhar, o Future fornece um código de resposta negativa (NRC) em conformidade com a ISO 14229-1 através de DiagUdsNrcErrc [SWS_DM_01332]. O método está especificado como noexcept e seguro em termos de exceções (exception safe) [SWS_DM_01332]. A segurança entre threads é condicional: a necessidade de implementar a função como segura entre threads é definida através do ConcurrencyType passado no construtor [SWS_DM_01332].

usar

O método RequestReadFile é chamado pela instância do Diagnostic Server assim que é recebido um pedido de diagnóstico para RequestFileTransfer (0x38) com o modo de operação ReadFile (0x04) [SWS_DM_01314]. A função aceita o caminho do ficheiro incluindo o nome (fileName), o formato dos dados (dataFormatIdentifier), metadados do pedido (metaInfo), bem como um cancellationHandler [SWS_DM_01331]. Através do cancellationHandler, o estado de cancelamento pode ser consultado (IsCanceled) ou pode ser registada uma função de notificação para o cancelamento da conversação atual (SetNotifier) [SWS_DM_01331].

A execução ocorre de forma assíncrona e devolve um ara::core::Future. Em caso de sucesso, o future fornece um tuplo de DataTransferReadSession e FileSizes [SWS_DM_01331]. Em FileSizes, um valor de 0 para uncompressed_size ou compressed_size sinaliza que o respetivo tamanho não é transmitido ao cliente UDS; em ficheiros não comprimidos, compressed_size tem de ser definido como zero [SWS_DM_01331].

Tratamento de erros

Se a preparação do processo de leitura falhar, a aplicação reporta um UDS-NRC adequado em conformidade com a ISO 14229-1 através de DiagUdsNrcErrc no future devolvido [SWS_DM_01331].

Concorrência e interação

A função está declarada como noexcept. A segurança entre threads é condicional (conditional): quem decide se a implementação tem de ser concebida como segura entre threads é o ConcurrencyType passado ao construtor [SWS_DM_01331]. O objeto DataTransferReadSession devolvido constitui o elemento de ligação entre o processamento de RequestFileTransfer e os subsequentes serviços TransferData (0x36), através dos quais o fluxo de dados do ficheiro propriamente dito é transmitido SWS Diagnostics p. 184.

O método RequestResumeWriteFile é chamado por uma instância do Diagnostic Server quando é recebido um pedido de serviço UDS para RequestFileTransfer (0x38) com o modo de operação ResumeFile (0x06) ([SWS_DM_01316], SWS Diagnostics §[SWS_DM_01316] «Realization of modeOfOperation ResumeFile (0x06)»). O seu objetivo é o reatamento de um processo de escrita de um ficheiro previamente interrompido.

Aquando da chamada, são passados o caminho do ficheiro (fileName), o identificador de formato de dados UDS (dataFormatIdentifier), os tamanhos do ficheiro (fileSizes), metadados do pedido (metaInfo), bem como um cancellationHandler ([SWS_DM_01334], SWS Diagnostics §8.18.1.2.3.5 «RequestResumeWriteFile»). Através do cancellationHandler, a aplicação pode verificar ativamente mediante IsCanceled se a conversação de diagnóstico em curso foi cancelada, ou registar via SetNotifier uma função de notificação para um cancelamento ([SWS_DM_01334]).

O retorno ocorre de forma assíncrona através de ara::core::Future<std::tuple<DataTransferWriteSession, std::uint64_t>> ([SWS_DM_01334]). Em caso de sucesso, o future disponibiliza um tuplo que contém uma instância da DataTransferWriteSession, bem como a posição de byte a partir da qual a transferência deve ser continuada ([SWS_DM_01334]). Este objeto de sessão associa a inicialização por RequestFileTransfer aos subsequentes serviços TransferData (0x36) (SWS Diagnostics §[SWS_DM_01316] «Realization of modeOfOperation ResumeFile (0x06)»).

Em caso de erro, o future deve ser terminado com um UDS-NRC adequado em conformidade com a ISO 14229-1 através de DiagUdsNrcErrc ([SWS_DM_01334]). A função está declarada como noexcept e é segura em termos de exceções; a segurança entre threads é condicional («conditional») e é definida pelo ConcurrencyType passado no construtor ([SWS_DM_01334]).

usar

O método [SWS_DM_01333] é chamado pelo servidor de diagnóstico assim que é recebido um pedido de serviço UDS RequestFileTransfer (0x38) com o modo de funcionamento WriteFile ([SWS_DM_01310]). Se o pedido for transmitido com o modo de funcionamento ReplaceFile (0x03), o servidor de diagnóstico chama a interface com o modo de escrita kReplace ([SWS_DM_01313]). A chamada passa o nome do ficheiro (fileName), o identificador do formato de dados (dataFormatIdentifier), tamanhos de ficheiro (fileSizes), o modo de substituição (mode), metadados adicionais (metaInfo), bem como um cancellationHandler. A indicação da especificação «file to read» no parâmetro fileName deverá ser um lapso editorial e designa o caminho de destino do ficheiro a escrever. Pergunta Q-f14158fc20fda8af (aberta)

O processamento ocorre de forma assíncrona e devolve um ara::core::Future<DataTransferWriteSession> ([SWS_DM_01333]). A sessão resultante serve como elemento de ligação entre a inicialização através do serviço 0x38 e as subsequentes transferências de dados via TransferData (0x36) (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.20 «Service 0x38 – RequestFileTransfer»).

Tratamento de erros e simultaneidade

O método está declarado como noexcept. Se ocorrer um erro, não é lançado nenhum erro de C++, mas é devolvido no future um UDS-NRC adequado de DiagUdsNrcErrc em conformidade com a ISO 14229-1 ([SWS_DM_01333]). Através do cancellationHandler passado, é possível consultar o estado de cancelamento mediante IsCanceled() ou registar uma notificação com SetNotifier(), caso a conversação de diagnóstico seja interrompida. A segurança entre threads é condicional: a necessidade de implementar a função como segura entre threads é definida através do ConcurrencyType no construtor ([SWS_DM_01333]).

Interação

A operação complementa a interação dos serviços de transferência de ficheiros e surge como complementar a operações de leitura como RequestReadFile ([SWS_DM_01314]) ou ao reatamento de processos de escrita interrompidos via RequestResumeWriteFile ([SWS_DM_01316]).

A função StopOffer da classe ara::diag::FileTransferService serve para cancelar o registo do serviço perante o Diagnostic Management ([SWS_DM_01337]; AUTOSAR_AP_SWS_Diagnostics §8.18.1.2.3.7 «StopOffer»). A sua chamada faz com que o DM deixe de encaminhar pedidos de diagnóstico recebidos para esta instância de serviço a partir desse momento. A interface está definida no cabeçalho #include "ara/diag/file_transfer.h", possui a assinatura void StopOffer() const noexcept;, não espera parâmetros e não devolve nenhum valor de retorno. A chamada é executada de forma síncrona.

Não está previsto qualquer mecanismo de erro para StopOffer. O método está declarado como seguro em termos de exceções (exception safe) e com o identificador noexcept ([SWS_DM_01337]). Não são geradas exceções nem são devolvidos códigos de erro à aplicação. A desativação do encaminhamento não falha do ponto de vista da API.

De acordo com a especificação, StopOffer está classificado como não seguro entre threads (not thread-safe) ([SWS_DM_01337]). Por isso, os acessos paralelos à mesma instância de ara::diag::FileTransferService têm de ser protegidos contra concorrência do lado da aplicação. Interpretação: a desativação deverá ocorrer tipicamente antes da destruição do objeto ou durante um encerramento ordenado da aplicação de processamento, para que não entrem pedidos numa rotina que já não se encontre operacional. Pergunta Q-e7bb2a5621c39160 (aberta)

A desativação através de StopOffer segue o padrão arquitetural uniforme da AUTOSAR Adaptive para serviços de diagnóstico disponibilizados. Corresponde a funções de desativação semelhantes de classes afins como ara::diag::DownloadService ([SWS_DM_00793]), ara::diag::UploadService ([SWS_DM_00803]), ara::diag::CommunicationControl ([SWS_DM_00810]) e ara::diag::Monitor ([SWS_DM_01089]; AUTOSAR_AP_SWS_Diagnostics §7.3.4.1.2 «Monitors»).