chromium/third_party/ipcz/src/ipcz/message.h

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef IPCZ_SRC_IPCZ_MESSAGE_H_
#define IPCZ_SRC_IPCZ_MESSAGE_H_

#include <cstddef>
#include <cstdint>
#include <optional>

#include "ipcz/driver_object.h"
#include "ipcz/driver_transport.h"
#include "ipcz/ipcz.h"
#include "ipcz/sequence_number.h"
#include "third_party/abseil-cpp/absl/base/macros.h"
#include "third_party/abseil-cpp/absl/container/inlined_vector.h"
#include "third_party/abseil-cpp/absl/types/span.h"
#include "util/safe_math.h"

namespace ipcz {

namespace internal {

// All wire structures defined in this header should be declared between this
// line and the corresponding #pragma pack(pop). Fields in these structures
// should manually aligned with explicit padding fields as needed.
#pragma pack(push, 1)

// Header which begins all messages. The header layout is versioned for
// extensibility and long-term support.
struct MessageHeader { … };
static_assert …;

MessageHeaderV0;
LatestMessageHeaderVersion;

// Header encoding metadata about a structure within a message.
struct StructHeader { … };
static_assert …;

// Header encoding metadata about any array within a message.
struct ArrayHeader { … };

// Each serialized driver object is represented as an array of bytes and an
// array of driver handles. This structure describes both arrays for a single
// driver object. For every object attached to a message, there one of these
// structs.
struct DriverObjectData { … };

// Encodes information about a range of driver objects. Used to encode
// DriverObject array parameters.
struct DriverObjectArrayData { … };

// Encodes an invalid driver object index. Any driver object field encoded as
// this value will deserialize to an invalid DriverObject.
constexpr uint32_t kInvalidDriverObjectIndex = …;

// End of wire structure definitions. Anything below this line is not meant to
// be encoded into messages.
#pragma pack(pop)

// Message macros emit metadata structures which are used at runtime to help
// validate an encoded message during deserialization. This conveys the kind of
// each field within the message's parameter structure.
enum class ParamType { … };

// Metadata about a single parameter declared within a message via one of the
// IPCZ_MSG_PARAM* macros. Constants of this type are genereated by such macros.
// See documentation in message_versions_declaration_macros.h and
// message_base_declaration_macros.h.
struct ParamMetadata { … };

// Metadata about a single message version. Note that versions are additive:
// "version 0" refers only to the fields defined for version 0 of a message;
// "version 1" refers only to the fields added for version 1. More generally, a
// message with a "version N" block also has a block for all versions from 0 to
// N-1, and all blocks are non-overlapping.
//
// Constants of this type are genereated by IPCZ_MSG_PARAM* macros. See
// documentation in message_versions_declaration_macros.h and
// message_base_declaration_macros.h.
struct VersionMetadata { … };

}  // namespace internal

// Message helps build, serialize, and deserialize ipcz-internal messages.
class IPCZ_ALIGN(8) Message { … };

// Template helper to wrap the Message type for a specific macro-generated
// parameter structure. This primarily exists for safe, convenient construction
// of message payloads with correct header information and no leaky padding
// bits, as well as for convenient access to parameters within size-validated,
// deserialized messages.
//
// When an IPCZ_MSG_BEGIN() macro is used to declare a new Foo message, it will
// emit both a msg::Foo_Params structure for the fixed wire data of the message
// parameters, as well as a msg::Foo which is an alias for an instance of this
// template, namely Message<msg::Foo_Params>.
template <typename ParamDataType>
class MessageWithParams : public Message { … };

}  // namespace ipcz

#endif  // IPCZ_SRC_IPCZ_MESSAGE_H_