Weave Packet Receiver

components/proximity_auth/ble/bluetooth_low_energy_weave_packet_receiver.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef COMPONENTS_PROXIMITY_AUTH_BLE_BLUETOOTH_LOW_ENERGY_WEAVE_PACKET_RECEIVER_H_
+#define COMPONENTS_PROXIMITY_AUTH_BLE_BLUETOOTH_LOW_ENERGY_WEAVE_PACKET_RECEIVER_H_
+
+#include <stdint.h>
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "components/proximity_auth/ble/bluetooth_low_energy_weave_packet_generator.h"
+
+namespace proximity_auth {
+// TODO(jingxuy): move the enums from BluetoothLowEnergyWeavePacketGenerator to
+// a shared location
+
+// Receive the messages sent with uWeave protocol.
+// Example Usage:
+// State state = ReceivePacket(packet);
+// switch (state) {
+// case ReceiverState::DATA_READY:
+//   OnBytesReceived(GetDataMessage());
+//   break;
+// case ReceiverState::CONNECTION_CLOSED:
+//   Disconnect();
+//   break;
+// case ReceiverState::ERROR:
+//   HandleError();
+//   break;
+// case ReceiverState::CONNECTING:
+// case ReceiverState::WAITING:
+// case ReceiverState::RECEIVING_DATA:
+//   break;
+// default:
+//   FoundABugInReceiver();
+//   break;
+// }
+class BluetoothLowEnergyWeavePacketReceiver {
+ public:
+  enum ReceiverType { CLIENT, SERVER };
+
+  class Factory {
+   public:
+    static std::unique_ptr<BluetoothLowEnergyWeavePacketReceiver> NewInstance(
+        ReceiverType receiver_type);
+
+    // Exposed for testing.
+    static void SetInstanceForTesting(Factory* factory);
+
+   protected:
+    // Exposed for testing.
+    BluetoothLowEnergyWeavePacketReceiver* BuildInstance(
+        ReceiverType receiver_type);
+
+   private:
+    static Factory* factory_instance_;
+  };
+
+  // CONNECTING:
+  //   The connection hasn't been estabalished. Accept a CONNECTION_REQUEST if
+  //   the receiver is a SERVER. Accept a CONNECTION_RESPONSE if the receiver is
+  //   a CLIENT. All other packets cause the receiver to move into ERROR state.
+  //   The state will transition to WAITING after a request/response if they
+  //   do not have extra data. The state will transition to DATA_READY if the
+  //   request/response have extra data since the extra data is treated as a
+  //   complete data message. This state is never reentered.
+  // WAITING:
+  //   The reciever is ready but doesn't have any data. It's waiting for packet
+  //   to arrive. Will accept all but connection request/response packets. The
+  //   first data packet will move the receiver to the RECEIVING_DATA state. A
+  //   connection close packet will move the receiver to the CONNECTION_CLOSED
+  //   state. This state is also never reentered.
+  // RECEIVING_DATA:
+  //   The receiver is in middle of receiving a data message consisted of
+  //   multiple packets. Will receive only data packets. The last data packet
+  //   will move the receiver into DATA_READY state. This state can be entered
+  //   once from WAITING and unlimited number of times from DATA_READY.
+  // DATA_READY:
+  //   The data message is ready to be retrieved. If the data is not retrieved
+  //   before the next packet which will cause a transition, the data will be
+  //   lost. Move to RECEIVING_DATA on receiving first data packet. Move to
+  //   CONNECTION_CLOSED on receiving close. This state can be entered once from
+  //   CONNECTICNG and unlimited number of times from RECEIVING_DATA.
+  // CONNECTION_CLOSED:
+  //   The connection is closed. Refuse any further messages. Allow the reason
+  //   for close to be retrieved.
+  // ERROR:
+  //   Something bad happened along the way. Allow a reason to close be
+  //   retrieved. The reason to close tells the receiver's user what reason to
+  //   close the connection in case the user wants to send a CONNECTION_CLOSE.
+  enum State {
+    CONNECTING = 0x00,
+    WAITING = 0x01,
+    RECEIVING_DATA = 0x02,
+    DATA_READY = 0x03,
+    CONNECTION_CLOSED = 0x04,
+    ERROR = 0x05
+  };
+
+  ~BluetoothLowEnergyWeavePacketReceiver();
+
+  typedef std::vector<uint8_t> Packet;
+
+  // Get the receiver’s state.
+  State GetState();
+
+  // Return the packet size that the receiver parsed out of request/response.
+  uint16_t GetMaxPacketSize();
+
+  // Get the reason that receiver received in a connection close packet.
+  // It's only defined in CONNECTION_CLOSED state.
+  // Will crash unless receiver is in State::CONNECTION_CLOSED.
+  BluetoothLowEnergyWeavePacketGenerator::ReasonForClose GetReasonForClose();
+
+  // The reason that the receiver decided to enter the ERROR state.
+  // This would be the reason that the receiver's want to send a connection
+  // close to the other side of the connection.
+  // Will crash unless receiver is in State::ERROR.
+  BluetoothLowEnergyWeavePacketGenerator::ReasonForClose GetReasonToClose();
+
+  // Get a complete data message that's yet received.
+  // Will crash unless receiver is in State::DATA_READY.
+  // NOTE: if this function is not called in DATA_READY state and the receiver
+  // transitions out of that state, the data will be gone!
+  std::string GetDataMessage();
+
+  // Add a packet that's just been received over Connection to the receiver.
+  State ReceivePacket(const Packet& packet);
+
+ protected:
+  explicit BluetoothLowEnergyWeavePacketReceiver(ReceiverType receiver_type);
+
+ private:
+  void ReceiveFirstPacket(const Packet& packet);
+  void ReceiveNonFirstPacket(const Packet& packet);
+
+  void ReceiveConnectionRequest(const Packet& packet);
+  void ReceiveConnectionResponse(const Packet& packet);
+  void ReceiveConnectionClose(const Packet& packet);
+  void AppendData(const Packet& packet, uint32_t byte_offset);
+
+  uint16_t GetShortField(const Packet& packet, uint32_t byte_offset);
+  uint8_t GetPacketType(const Packet& packet);
+  uint8_t GetControlCommand(const Packet& packet);
+  void VerifyPacketCounter(const Packet& packet);
+  bool IsFirstDataPacket(const Packet& packet);
+  bool IsLastDataPacket(const Packet& packet);
+  bool AreLowerTwoBitsCleared(const Packet& packet);
+
+  void MoveToErrorState(
+      BluetoothLowEnergyWeavePacketGenerator::ReasonForClose reason_to_close);
+
+  void SetMaxPacketSize(uint16_t packet_size);
+  uint16_t GetConceptualMaxPacketSize();
+
+  // Identify whether the receiver is for a client or a server.
+  ReceiverType receiver_type_;
+
+  // Max packet size of the connection.
+  // Default is 0 which means the server will determine the size by observing
+  // ATT_MTU of the client.
+  uint16_t max_packet_size_;
+
+  // Expected counter of the next packet received, starting at 0.
+  uint32_t next_packet_number_;
+
+  // Current state of the receiver.
+  // Certain functions will only return valid value if the receiver is in the
+  // appropriate state.
+  State state_;
+
+  // The reason why the connection was closed by the sender if any.
+  BluetoothLowEnergyWeavePacketGenerator::ReasonForClose reason_for_close_;
+
+  // The reason why the receiver is in an erronous state if any.
+  BluetoothLowEnergyWeavePacketGenerator::ReasonForClose reason_to_close_;
+
+  // The data message if there is one.
+  Packet data_message_;
+};
+
+}  // namespace proximity_auth
+
+#endif  // COMPONENTS_PROXIMITY_AUTH_BLE_BLUETOOTH_LOW_ENERGY_WEAVE_PACKET_RECEIVER_H_