mojo/public/cpp/bindings/tests/validation_test_input_parser.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MOJO_PUBLIC_CPP_BINDINGS_TESTS_VALIDATION_TEST_INPUT_PARSER_H_
   6 #define MOJO_PUBLIC_CPP_BINDINGS_TESTS_VALIDATION_TEST_INPUT_PARSER_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11 #include <vector>
  12
  13 namespace mojo {
  14 namespace test {
  15
  16 // Input Format of Mojo Message Validation Tests.
  17 //
  18 // Data items are separated by whitespaces:
  19 //   - ' ' (0x20) space;
  20 //   - '\t' (0x09) horizontal tab;
  21 //   - '\n' (0x0a) newline;
  22 //   - '\r' (0x0d) carriage return.
  23 // A comment starts with //, extending to the end of the line.
  24 // Each data item is of the format [<type>]<value>. The types defined and the
  25 // corresponding value formats are described below.
  26 //
  27 // Type: u1 / u2 / u4 / u8
  28 // Description: Little-endian 1/2/4/8-byte unsigned integer.
  29 // Value Format:
  30 //   - Decimal integer: 0|[1-9][0-9]*
  31 //   - Hexadecimal integer: 0[xX][0-9a-fA-F]+
  32 //   - The type prefix (including the square brackets) of 1-byte unsigned
  33 //   integer is optional.
  34 //
  35 // Type: s1 / s2 / s4 / s8
  36 // Description: Little-endian 1/2/4/8-byte signed integer.
  37 // Value Format:
  38 //   - Decimal integer: [-+]?(0|[1-9][0-9]*)
  39 //   - Hexadecimal integer: [-+]?0[xX][0-9a-fA-F]+
  40 //
  41 // Type: b
  42 // Description: Binary sequence of 1 byte.
  43 // Value Format: [01]{8}
  44 //
  45 // Type: f / d
  46 // Description: Little-endian IEEE-754 format of float (4 bytes) and double (8
  47 // bytes).
  48 // Value Format: [-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?
  49 //
  50 // Type: dist4 / dist8
  51 // Description: Little-endian 4/8-byte unsigned integer. The actual value is set
  52 // to the byte distance from the location of this integer to the location of the
  53 // anchr item with the same ID. A dist8 and anchr pair can be used to easily
  54 // represent an encoded pointer. A dist4 and anchr pair can be used to easily
  55 // calculate struct/array size.
  56 // Value Format: The value is an ID: [0-9a-zA-Z_]+
  57 //
  58 // Type: anchr
  59 // Description: Mark an anchor location. It doesn’t translate into any actual
  60 // data.
  61 // Value Format: The value is an ID of the same format as that of dist4/8.
  62 //
  63 // Type: handles
  64 // Description: The number of handles that are associated with the message. This
  65 // special item is not part of the message data. If specified, it should be the
  66 // first item.
  67 // Value Format: The same format as u1/2/4/8.
  68 //
  69 // EXAMPLE:
  70 //
  71 // Suppose you have the following Mojo types defined:
  72 //   struct Bar {
  73 //     int32 a;
  74 //     bool b;
  75 //     bool c;
  76 //   };
  77 //   struct Foo {
  78 //     Bar x;
  79 //     uint32 y;
  80 //   };
  81 //
  82 // The following describes a valid message whose payload is a Foo struct:
  83 //   // message header
  84 //   [dist4]message_header   // num_bytes
  85 //   [u4]3                   // num_fields
  86 //   [u4]0                   // type
  87 //   [u4]1                   // flags
  88 //   [u8]1234                // request_id
  89 //   [anchr]message_header
  90 //
  91 //   // payload
  92 //   [dist4]foo      // num_bytes
  93 //   [u4]2           // num_fields
  94 //   [dist8]bar_ptr  // x
  95 //   [u4]0xABCD      // y
  96 //   [u4]0           // padding
  97 //   [anchr]foo
  98 //
  99 //   [anchr]bar_ptr
 100 //   [dist4]bar   // num_bytes
 101 //   [u4]3        // num_fields
 102 //   [s4]-1       // a
 103 //   [b]00000010  // b and c
 104 //   0 0 0        // padding
 105 //   [anchr]bar
 106
 107 // Parses validation test input.
 108 // On success, |data| and |num_handles| store the parsing result,
 109 // |error_message| is cleared; on failure, |error_message| is set to a message
 110 // describing the error, |data| is cleared and |num_handles| set to 0.
 111 // Note: For now, this method only works on little-endian platforms.
 112 bool ParseValidationTestInput(const std::string& input,
 113                               std::vector<uint8_t>* data,
 114                               size_t* num_handles,
 115                               std::string* error_message);
 116
 117 }  // namespace test
 118 }  // namespace mojo
 119
 120 #endif  // MOJO_PUBLIC_CPP_BINDINGS_TESTS_VALIDATION_TEST_INPUT_PARSER_H_