upb/message/message.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2023 Google LLC.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Public APIs for message operations that do not depend on the schema.
0009 //
0010 // MiniTable-based accessors live in accessors.h.
0011
0012 #ifndef UPB_MESSAGE_MESSAGE_H_
0013 #define UPB_MESSAGE_MESSAGE_H_
0014
0015 #include <stddef.h>
0016 #include <stdint.h>
0017
0018 #include "upb/base/string_view.h"
0019 #include "upb/mem/arena.h"
0020 #include "upb/message/array.h"
0021 #include "upb/message/internal/extension.h"
0022 #include "upb/message/internal/message.h"
0023 #include "upb/message/internal/types.h"
0024 #include "upb/mini_table/extension.h"
0025 #include "upb/mini_table/message.h"
0026
0027 // Must be last.
0028 #include "upb/port/def.inc"
0029
0030 typedef struct upb_Message upb_Message;
0031
0032 #ifdef __cplusplus
0033 extern "C" {
0034 #endif
0035
0036 // Creates a new message with the given mini_table on the given arena.
0037 UPB_API upb_Message* upb_Message_New(const upb_MiniTable* m, upb_Arena* arena);
0038
0039 //
0040 // Unknown data may be stored non-contiguously. Each segment stores a block of
0041 // unknown fields. To iterate over segments:
0042 //
0043 //   uintptr_t iter = kUpb_Message_UnknownBegin;
0044 //   upb_StringView data;
0045 //   while (upb_Message_NextUnknown(msg, &data, &iter)) {
0046 //     // Use data
0047 //   }
0048 // Iterates in the order unknown fields were parsed.
0049
0050 #define kUpb_Message_UnknownBegin 0
0051 #define kUpb_Message_ExtensionBegin 0
0052
0053 UPB_INLINE bool upb_Message_NextUnknown(const upb_Message* msg,
0054                                         upb_StringView* data, uintptr_t* iter);
0055
0056 UPB_INLINE bool upb_Message_HasUnknown(const upb_Message* msg);
0057
0058 // Removes a segment of unknown data from the message, advancing to the next
0059 // segment.  Returns false if the removed segment was at the end of the last
0060 // chunk.
0061 //
0062 // This must be done while iterating:
0063 //
0064 //   uintptr_t iter = kUpb_Message_UnknownBegin;
0065 //   upb_StringView data;
0066 //   // Iterate chunks
0067 //   while (upb_Message_NextUnknown(msg, &data, &iter)) {
0068 //     // Iterate within a chunk, deleting ranges
0069 //     while (ShouldDeleteSubSegment(&data)) {
0070 //       // Data now points to the region to be deleted
0071 //       switch (upb_Message_DeleteUnknown(msg, &data, &iter)) {
0072 //         case kUpb_Message_DeleteUnknown_DeletedLast: return ok;
0073 //         case kUpb_Message_DeleteUnknown_IterUpdated: break;
0074 //         // If DeleteUnknown returned kUpb_Message_DeleteUnknown_IterUpdated,
0075 //         // then data now points to the remaining unknown fields after the
0076 //         // region that was just deleted.
0077 //         case kUpb_Message_DeleteUnknown_AllocFail: return err;
0078 //       }
0079 //     }
0080 //   }
0081 //
0082 // The range given in `data` must be contained inside the most recently
0083 // returned region.
0084 typedef enum upb_Message_DeleteUnknownStatus {
0085   kUpb_DeleteUnknown_DeletedLast,
0086   kUpb_DeleteUnknown_IterUpdated,
0087   kUpb_DeleteUnknown_AllocFail,
0088 } upb_Message_DeleteUnknownStatus;
0089 upb_Message_DeleteUnknownStatus upb_Message_DeleteUnknown(upb_Message* msg,
0090                                                           upb_StringView* data,
0091                                                           uintptr_t* iter,
0092                                                           upb_Arena* arena);
0093
0094 // Returns the number of extensions present in this message.
0095 size_t upb_Message_ExtensionCount(const upb_Message* msg);
0096
0097 // Iterates extensions in wire order
0098 UPB_INLINE bool upb_Message_NextExtension(const upb_Message* msg,
0099                                           const upb_MiniTableExtension** out_e,
0100                                           upb_MessageValue* out_v,
0101                                           uintptr_t* iter);
0102
0103 // Iterates extensions in reverse wire order
0104 UPB_INLINE bool UPB_PRIVATE(_upb_Message_NextExtensionReverse)(
0105     const struct upb_Message* msg, const upb_MiniTableExtension** out_e,
0106     upb_MessageValue* out_v, uintptr_t* iter);
0107
0108 // Mark a message and all of its descendents as frozen/immutable.
0109 UPB_API void upb_Message_Freeze(upb_Message* msg, const upb_MiniTable* m);
0110
0111 // Returns whether a message has been frozen.
0112 UPB_API_INLINE bool upb_Message_IsFrozen(const upb_Message* msg);
0113
0114 #ifdef UPB_TRACING_ENABLED
0115 UPB_API void upb_Message_LogNewMessage(const upb_MiniTable* m,
0116                                        const upb_Arena* arena);
0117
0118 UPB_API void upb_Message_SetNewMessageTraceHandler(
0119     void (*handler)(const upb_MiniTable* m, const upb_Arena* arena));
0120 #endif  // UPB_TRACING_ENABLED
0121
0122 #ifdef __cplusplus
0123 } /* extern "C" */
0124 #endif
0125
0126 #include "upb/port/undef.inc"
0127
0128 #endif /* UPB_MESSAGE_MESSAGE_H_ */