zircon/system/ulib/fidl/include/lib/fidl/coding.h

// Copyright 2017 The Fuchsia 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 LIB_FIDL_CODING_H_
#define LIB_FIDL_CODING_H_

#include <zircon/compiler.h>
#include <zircon/fidl.h>
#include <zircon/types.h>

__BEGIN_CDECLS

// The maximum recursion depth the fidl encoder or decoder will
// perform. Each nested aggregate type (structs, unions, arrays,
// vectors, or tables) counts as one step in the recursion depth.
#define FIDL_RECURSION_DEPTH 32

// See
// https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/tutorial-c#fidl_encode-fidl_encode_msg
zx_status_t fidl_encode(const fidl_type_t* type, void* bytes, uint32_t num_bytes,
                        zx_handle_t* handles, uint32_t max_handles, uint32_t* out_actual_handles,
                        const char** out_error_msg);
zx_status_t fidl_encode_etc(const fidl_type_t* type, void* bytes, uint32_t num_bytes,
                            zx_handle_disposition_t* handle_dispositions,
                            uint32_t max_handle_dispositions,
                            uint32_t* out_actual_handle_dispositions, const char** out_error_msg);
// Populates an array of zx_channel_iovec_t and an array of zx_handle_t representing the encoded
// object. The motivation for using this is that in some cases performance may improve when used
// in conjuction with the ZX_CHANNEL_WRITE_IOVEC option for channel writes by avoiding
// a buffer allocation and copy. See RFC-0010 for more background.
// Pointers in the input object may have been overwritten during the encode process and a list of
// substitutions to recreate the original value is appended to the fidl_iovec_substitution_t list.
// Handles will be overwritten with ZX_HANDLE_INVALID but will not appear in the substitution
// list.
zx_status_t fidl_encode_iovec(const fidl_type_t* type, void* object, zx_channel_iovec_t* iovecs,
                              uint32_t max_iovecs, fidl_iovec_substitution_t* subs,
                              uint32_t max_subs, zx_handle_t* handles, uint32_t max_handles,
                              uint32_t* out_actual_iovecs, uint32_t* out_actual_subs,
                              uint32_t* out_actual_handles, const char** out_error_msg);
zx_status_t fidl_encode_iovec_etc(const fidl_type_t* type, void* object, zx_channel_iovec_t* iovecs,
                                  uint32_t max_iovecs, fidl_iovec_substitution_t* subs,
                                  uint32_t max_subs, zx_handle_disposition_t* handles,
                                  uint32_t max_handles, uint32_t* out_actual_iovecs,
                                  uint32_t* out_actual_subs, uint32_t* out_actual_handles,
                                  const char** out_error_msg);
zx_status_t fidl_encode_msg(const fidl_type_t* type, fidl_outgoing_msg_t* msg,
                            uint32_t* out_actual_handles, const char** out_error_msg);

// fidl_linearize_and_encode converts an object and its children to a FIDL wire-format
// compatible byte array.
//
// As part of this,
// - Objects are "linearized", meaning they are laid out as a contiguous block in FIDL-wire format
// order. The object is walked by following pointers in depth-first order and each encountered
// block is copied in order encountered.
// - Pointers in the output buffer are replaced with FIDL_ALLOC_PRESENT or FIDL_ALLOC_ABSENT
// markers.
// - Handles in the output buffer are replaced with FIDL_HANDLE_PRESENT or FIDL_HANDLE_ABSENT
// markers.
// - Input handles are consumed and the values in the input object are replaced with
// ZX_HANDLE_INVALID.
// - Padding is zeroed in between struct fields and in between out of line values.
// - The buffer is validated to match the requirements of the FIDL wire format.
//
// On success, handles in the original object will be moved to the |out_handles| array.
// On failure, handles in the original object will be closed.
zx_status_t fidl_linearize_and_encode(const fidl_type_t* type, void* value, uint8_t* out_bytes,
                                      uint32_t num_bytes, zx_handle_t* out_handles,
                                      uint32_t num_handles, uint32_t* out_num_actual_bytes,
                                      uint32_t* out_num_actual_handles, const char** out_error_msg);
zx_status_t fidl_linearize_and_encode_etc(const fidl_type_t* type, void* value, uint8_t* out_bytes,
                                          uint32_t num_bytes, zx_handle_disposition_t* out_handles,
                                          uint32_t num_handles, uint32_t* out_num_actual_bytes,
                                          uint32_t* out_num_actual_handles,
                                          const char** out_error_msg);
zx_status_t fidl_linearize_and_encode_msg(const fidl_type_t* type, void* value,
                                          fidl_outgoing_msg_t* msg, uint32_t* out_num_actual_bytes,
                                          uint32_t* out_num_actual_handles,
                                          const char** out_error_msg);

// See
// https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/tutorial-c#fidl_encode-fidl_encode_msg
zx_status_t fidl_decode(const fidl_type_t* type, void* bytes, uint32_t num_bytes,
                        const zx_handle_t* handles, uint32_t num_handles,
                        const char** error_msg_out);
// Perform a fidl_decode, but leave unknown handles in flexible resource types intact
// instead of closing them.
zx_status_t fidl_decode_skip_unknown_handles(const fidl_type_t* type, void* bytes,
                                             uint32_t num_bytes, const zx_handle_t* handles,
                                             uint32_t num_handles, const char** error_msg_out);

// Perform a fidl_decode and check handle types and rights against the types and rights specified
// in the FIDL file.
//
// It is an error for a zx_handle_info_t to contain a handle type that does not match what is
// expected from FIDL unless either the expected or actual type is ZX_OBJ_TYPE_NONE.
// It is also error if there are fewer actual rights than expected rights and the actual or
// expected rights are not ZX_RIGHT_SAME_RIGHTS. If there are more actual rights than expected
// rights, the actual rights will be reduced to the expected rights via a call to
// zx_handle_replace.
zx_status_t fidl_decode_etc(const fidl_type_t* type, void* bytes, uint32_t num_bytes,
                            const zx_handle_info_t* handle_infos, uint32_t num_handle_infos,
                            const char** error_msg_out);

// Perform a fidl_decode_etc, but leave unknown handles in flexible resource types intact
// instead of closing them.
zx_status_t fidl_decode_etc_skip_unknown_handles(const fidl_type_t* type, void* bytes,
                                                 uint32_t num_bytes,
                                                 const zx_handle_info_t* handles,
                                                 uint32_t num_handles, const char** error_msg_out);
zx_status_t fidl_decode_msg(const fidl_type_t* type, fidl_incoming_msg_t* msg,
                            const char** out_error_msg);

// Validates an encoded message against the given |type|.
//
// The |bytes| are not modified.
zx_status_t fidl_validate(const fidl_type_t* type, const void* bytes, uint32_t num_bytes,
                          uint32_t num_handles, const char** out_error_msg);
zx_status_t fidl_validate_msg(const fidl_type_t* type, const fidl_outgoing_msg_t* msg,
                              const char** out_error_msg);

// Validates a FIDL string, and verifies that it is a well-formed UTF-8 code
// unit sequence. That is respect the UTF-8 encoding, and be formed solely of
// unicode scalar value, i.e. any Unicode code point except high-surrogate
// and low-surrogate code points.
//
// The |data| is not modified.
//
// See also http://www.unicode.org/versions/Unicode13.0.0/ch03.pdf#G7404
zx_status_t fidl_validate_string(const char* data, uint64_t size);

// Stores the name of a fidl type into the provided buffer.
// Truncates the name if it is too long to fit into the buffer.
// Returns the number of characters written into the buffer.
//
// Note: This function does not write a trailing NUL.
size_t fidl_format_type_name(const fidl_type_t* type, char* buffer, size_t capacity);

// The following functions are only available under Fuchsia.

#ifdef __Fuchsia__

// Traverses a decoded FIDL message starting at |value|, closing all handles within it.
// If the message is non-contiguous in memory, the function will follow pointers and close handles
// in any scattered out-of-line objects.
//
// Handle values in |value| are replaced with ZX_HANDLE_INVALID.
zx_status_t fidl_close_handles(const fidl_type_t* type, void* value, const char** out_error_msg);

#endif

__END_CDECLS

#endif  // LIB_FIDL_CODING_H_