# Explanation of ara::com API

## Introduction
* Some properities:
* Proxy (or Stub)/Skeleton approach
* Protocol independent API
* Queued communication with configurable receiver-side caches
* Zero-copy capable API with possibility to shift memory management to the middleware
* Data reception filtering
* ara::com only defines the API signatures and its behavior visible to the application developer.
* ara::com does not provide any kind of component model or framework, which would take care of things like component life cycle, management of program flow or simply setting up ara::com API objects according to the formal component description of the respective application

### High Level Structure
* ara::com uses **classical Proxy/Skeleton architectural pattern**
* data types:
* pointer types: for pointers to data transmitted via middleware
* collection types: for collections of data transmitted via middleware
* Types for async operation result management: ara::com relies on AUTOSAR AP specific data types
* Function wrappers: for various application side callback or handler functions to be called by the middleware
* (note: ara::com defines signature and expected behavior of those types, but does not provide an implementation. The idea of this approach is, that platform vendors could easily come up with their own optimized implementation of those types.)
* Error notification:
* Checked Errors/Exceptions: Checked Errors within ara::com API can only occur in the **context of a call of a service interface method**.
* Unchecked Errors/Exceptions: Unchecked Errors within ara::com API can occur in the context of any ara::com API call.
### API element
* instance identifiers:
* Instance identifiers are used within ara::com, on client/proxy side, when a specific instance of a service shall be searched for or — at the server/skeleton side — when a specific instance of a service is created.
* At ara::com API level the instance identifier is generally a technical binding specific identifier -> concrete content/structure of which such an instance identifier consists, is totally technology specific ,e.g. ,SOME/IP uses uint16 identifiers to distinguish different instances of the same service type.
* class "InstanceIdentifier" does provide a toString() method
* Since it is a core feature, that the technical binding used by an ara::com based application is defined/specified by the integrator during deployment, so any expectations from an ara::com software developer regarding its content/structure are typically invalid. -> software developer get such a highly binding specific ara::com::InstanceIdentifier to be used in ara::com API calls by an ara:com provided functionality, which translates a logical local name used typically by the software developer in his realm into the technology/binding specificara::com::InstanceIdentifier.
* developer using ara::com does not need to know anything about bindings and their specifics
* Integrators can adapt bindings in deployments
* The local name(InstanceSpecifier) from which the ara::com::InstanceIdentifier is constructed comes basically from AUTOSAR meta-model(InstanceIdentifier), describing your software component model. -> integrator/deployer can assign a dedicated technical binding with its specific instance IDs to those "instance specifier" via a "manifest file", which is specifically used for a distinct instantiation/execution of the executable.
> **ara::core::InstanceSpecifier(local name in the software developers realm)**
> **ara::com::InstanceIdentifier(AUTOSAR meta-model)**
> note: use functions provided by ara:com to do the translation between them
* mult-binding: AUTOSAR supports, that the integrator may configure multiple technical bindings behind one abstract identifier visible to the software component developer(used in server side in common)
* Proxy Class(creation through HandleType)
* Proxy class is generated from the service interface description of the AUTOSAR meta model.
* Finding Services:
* **StartFindService** is a class method, which starts a continuous “FindService” activity in the background, which notifies the caller via a given callback anytime the availability of instances of the service changes
* **FindService** is a one-off call, which returns available instances at the point in time of the call
* The ara::com design team decided to require this re-use possibility from the binding implementation as it eases the typical task of implementing service consumers(service instance comes up, notified via service discovery infrastructure and get auto update)
* All the event classes needed for the proxy class are generated inside a specific namespace events, which is contained inside the proxy namespace
* A typical usage pattern for an application developer, who wants to get notified about latest subscription state, would be to register a handler before the first call to Subscribe
* Calls to the registered “subscription state change” handler are done fully asynchronous. That means, they can even happen, while the call to Subscribe has not yet returned. The user has to be aware of this
* If a new subscription state change happens, while the user provided handler from a previous call of a state change is still running, the Communication Management implementation has to postpone the next call until the previous has returned
* **users can monitor the availability by 1.FindService 2. registered a “subscription state change” handler (then call handler)**
* the API "GetNewSamples" is to get/fetch those event samples from some buffers(e.g. kernel buffers, special IPC implementation controlled shared memory regions, ...), eventually deserialze it and and then put them into the event wrapper class instance specific cache in form of a correct SampleType
* There are three different places, where the buffer, which is target for the “send event” might be located:
* Kernel Space: Data is sent to a memory region not mapped directly to an application process. This is typically the case, when binding implementation uses IPC primitives like pipes or sockets, where data written to such a primitive ends up in kernel buffer space.
* Shared Memory: Data is sent to a memory region, which is also directly readable from receivers/proxies. Writing/reading between different parties is synchronized specifically (lightweight with mem barriers or with explicit mutexes).
* IPC-Daemon Space: Data is sent to an explicit non-application process, which acts as a kind of demon for the IPC/binding implementation. Note, that technically this approach might be built on an IPC primitive like communication via kernel space or shared memory to get the data from service process to demon process.
* method wrapper class consists of two parts: An inner structure definition, which aggregates all OUT-/INOUT-parameters of the method, and a bracket operator, which is used to call the service method.
* one-way method: this is a method with only IN-params — no OUT-params and no raising of errors allowed, The client/caller therefore gets no feedback at all, whether the server/callee has processed a “one-way” call or not
* 'GetResult()' returns a Result or an Error and throws no exception. Using 'get()' returns the corresponding future and throws exceptions if necessary.
* conceptually a **field** has — unlike an event — a certain value at any time
* Skeleton Class(generated from the service interface description of the AUTOSAR meta mode)
* Modes:
* Polling Mode
* Event-Driven Mode
* Methods:
* One-Way aka Fire-and-Forget Methods(no feedback possible/needed towards the caller)
* Raising Application Errors
* Events:
* On the skeleton side the service implementation is in charge of notifying about occurrence of an event
* Fields:
* On the skeleton side the service implementation is in charge of
* updating and notifying about changes of the value of a field
* serving incoming Get() calls
* serving incoming Set() calls
* Runtime:
* A singleton called Runtime may be needed to collect cross-cutting functionalities
* currently no needed this functionality
* Raw Data Streaming Interface
* Introduction:
* From the ara::com architecture point of view, Raw Data Streaming API is static, i.e. its is not generated. It is part of the ara::com namespace, but is independent of the ara::com middleware services
* The Raw Data Binary Stream API provides a way to send and receive Raw Binary Data Streams, which are sequences of bytes, without any data type. They enable efficient communication with external sensors in a vehicle (e.g. sensor delivers video and map data in "Raw data" format). The communication is performed over a network using sockets
* In principle, Raw Data Streaming can use any transport layer but currently only **TCP and UDP** are supported
* Functional description:
* The Raw Data Binary Stream API can be used in both the client or the server side. The functionality of both client and server allow to send and receive. The only difference is that the server can wait for connections but cannot actively connect to a client. On the other side, the client can connect to a server (that is already waiting for connections) but the client cannot wait for connections
* usage must follow this sequence:
* As client:
1. Connect: Establishes connection to sensor
2. ReadData/WriteData: Receives or sends data
3. Shutdown: Connection is closed
* As server:
1. WaitForConnection: Waits for incoming connections from clients
2. ReadData/WriteData: Receives or sends data
3. Shutdown: Connection is closed and stops waiting for connections
* Class and Model:
* ara::com::raw : defines a RawDataStream class for reading and writing binary data streams over a network connection using sockets
* ara::com::raw::RawDataStreamClient
* ara::com::raw::RawDataStreamServer
* Constructor
* The constructor takes as input the instance specifier qualifying the network binding and parameters for the instance
`RawDataStreamClient(const ara::com::InstanceSpecifier\& instance);`
* Destructor
* connection shutdown -> object dertroyed
* Manifest Model
* defines the parameters of the Raw Data Stream deployment
* Methods:
* Timeout parameter
* All the methods of RawDataStream have an optional input parameter for the timeout
* WaitForConnection
* only available in the server side
* Connect
* only available in the client side
* initializes the socket and establishes a connection to the TCP server
* The sockets are specified in the manifest which is accessed through the InstanceSpecifer provided in the constructor.
* Shutdown
* ReadData
* reads bytes from the socket connection
* WriteData
* writes bytes to the socket connection
 
* Security
* Raw Data Stream communication can be transported using TCP and UDP, so different security mechanisms are needed.
* Currently TLS, DTLS and IPSec
* **All security functions are configurable in the deployment and mapping model of Raw Data Streaming Interface**
* **Implementation of Raw Data Streaming interface should be independent from the underlying Sockets API (e.g. POSIX Sockets).**