src/isotp/receive.h

   1 #ifndef __ISOTP_RECEIVE_H__
   2 #define __ISOTP_RECEIVE_H__
   3
   4 #include <isotp/isotp.h>
   5 #include <stdint.h>
   6 #include <stdbool.h>
   7
   8 #ifdef __cplusplus
   9 extern "C" {
  10 #endif
  11
  12 /* Public: A handle for beginning and continuing receiving a single ISO-TP
  13  * message - both single and multi-frame.
  14  *
  15  * Since an ISO-TP message may contain multiple frames, we need to keep a handle
  16  * around while waiting for subsequent CAN messages to complete the message.
  17  * This struct encapsulates the local state required.
  18  *
  19  * completed - True if the received message request is completely finished.
  20  * success - True if the message request was successful. The value if this field
  21  *      isn't valid if 'completed' isn't true.
  22  */
  23 typedef struct {
  24     bool completed;
  25     bool success;
  26
  27     // Private
  28     uint16_t arbitration_id;
  29     IsoTpMessageReceivedHandler message_received_callback;
  30     uint16_t timeout_ms;
  31     // timeout_ms: ISO_TP_DEFAULT_RESPONSE_TIMEOUT,
  32     bool frame_padding;
  33     // frame_padding: ISO_TP_DEFAULT_FRAME_PADDING_STATUS,
  34     uint8_t* receive_buffer;
  35     uint16_t received_buffer_size;
  36     uint16_t incoming_message_size;
  37     // TODO timer callback for multi frame
  38 } IsoTpReceiveHandle;
  39
  40 /* Public: Initiate receiving a single ISO-TP message on a particular
  41  * arbitration ID.
  42  *
  43  * Note that no actual CAN data has been received at this point - this just sets
  44  * up a handle to be used when new CAN messages to arrive, so they can be parsed
  45  * as potential single or multi-frame ISO-TP messages.
  46  *
  47  * shims -  Low-level shims required to send and receive CAN messages, etc.
  48  * arbitration_id - The arbitration ID to receive the message on.
  49  * callback - an optional function to be called when the message is completely
  50  *      received (use NULL if no callback required).
  51  *
  52  * Returns a handle to be used with isotp_continue_receive when a new CAN frame
  53  * arrives. The 'completed' field in the returned IsoTpReceiveHandle will be true
  54  * when the message is completely sent.
  55  */
  56 IsoTpReceiveHandle isotp_receive(IsoTpShims* shims,
  57         const uint16_t arbitration_id, IsoTpMessageReceivedHandler callback);
  58
  59 /* Public: Continue to receive a an ISO-TP message, based on a freshly
  60  * received CAN message.
  61  *
  62  * For a multi-frame ISO-TP message, this function must be called
  63  * repeatedly whenever a new CAN message is received in order to complete
  64  * receipt.
  65  *
  66  * TODO does this API work for if we wanted to receive an ISO-TP message and
  67  * send our own flow control messages back?
  68  *
  69  * shims -  Low-level shims required to send and receive CAN messages, etc.
  70  * handle - An IsoTpReceiveHandle previously returned by isotp_receive(...).
  71  * arbitration_id - The arbitration_id of the received CAN message.
  72  * data - The data of the received CAN message.
  73  * size - The size of the data in the received CAN message.
  74  *
  75  * Returns an IsoTpMessage with the 'completed' field set to true if a message
  76  * was completely received. If 'completed' is false, more CAN frames are
  77  * required to complete the messages, or the arbitration ID didn't match this
  78  * handle. Keep passing the same handle to this function when CAN frames arrive.
  79  */
  80 IsoTpMessage isotp_continue_receive(IsoTpShims* shims,
  81         IsoTpReceiveHandle* handle, const uint16_t arbitration_id,
  82         const uint8_t data[], const uint8_t size);
  83
  84 #ifdef __cplusplus
  85 }
  86 #endif
  87
  88 #endif // __ISOTP_RECEIVE_H__