1 use alloc::boxed::Box; 2 use core::fmt::Debug; 3 use core::usize; 4 5 use bytes::{Buf, BufMut}; 6 7 use crate::encoding::{ 8 decode_key, encode_varint, encoded_len_varint, message, DecodeContext, WireType, 9 }; 10 use crate::DecodeError; 11 use crate::EncodeError; 12 13 /// A Protocol Buffers message. 14 pub trait Message: Debug + Send + Sync { 15 /// Encodes the message to a buffer. 16 /// 17 /// This method will panic if the buffer has insufficient capacity. 18 /// 19 /// Meant to be used only by `Message` implementations. 20 #[doc(hidden)] encode_raw<B>(&self, buf: &mut B) where B: BufMut, Self: Sized21 fn encode_raw<B>(&self, buf: &mut B) 22 where 23 B: BufMut, 24 Self: Sized; 25 26 /// Decodes a field from a buffer, and merges it into `self`. 27 /// 28 /// Meant to be used only by `Message` implementations. 29 #[doc(hidden)] merge_field<B>( &mut self, tag: u32, wire_type: WireType, buf: &mut B, ctx: DecodeContext, ) -> Result<(), DecodeError> where B: Buf, Self: Sized30 fn merge_field<B>( 31 &mut self, 32 tag: u32, 33 wire_type: WireType, 34 buf: &mut B, 35 ctx: DecodeContext, 36 ) -> Result<(), DecodeError> 37 where 38 B: Buf, 39 Self: Sized; 40 41 /// Returns the encoded length of the message without a length delimiter. encoded_len(&self) -> usize42 fn encoded_len(&self) -> usize; 43 44 /// Encodes the message to a buffer. 45 /// 46 /// An error will be returned if the buffer does not have sufficient capacity. encode<B>(&self, buf: &mut B) -> Result<(), EncodeError> where B: BufMut, Self: Sized,47 fn encode<B>(&self, buf: &mut B) -> Result<(), EncodeError> 48 where 49 B: BufMut, 50 Self: Sized, 51 { 52 let required = self.encoded_len(); 53 let remaining = buf.remaining_mut(); 54 if required > buf.remaining_mut() { 55 return Err(EncodeError::new(required, remaining)); 56 } 57 58 self.encode_raw(buf); 59 Ok(()) 60 } 61 62 #[cfg(feature = "std")] 63 /// Encodes the message to a newly allocated buffer. encode_to_vec(&self) -> Vec<u8> where Self: Sized,64 fn encode_to_vec(&self) -> Vec<u8> 65 where 66 Self: Sized, 67 { 68 let mut buf = Vec::with_capacity(self.encoded_len()); 69 70 self.encode_raw(&mut buf); 71 buf 72 } 73 74 /// Encodes the message with a length-delimiter to a buffer. 75 /// 76 /// An error will be returned if the buffer does not have sufficient capacity. encode_length_delimited<B>(&self, buf: &mut B) -> Result<(), EncodeError> where B: BufMut, Self: Sized,77 fn encode_length_delimited<B>(&self, buf: &mut B) -> Result<(), EncodeError> 78 where 79 B: BufMut, 80 Self: Sized, 81 { 82 let len = self.encoded_len(); 83 let required = len + encoded_len_varint(len as u64); 84 let remaining = buf.remaining_mut(); 85 if required > remaining { 86 return Err(EncodeError::new(required, remaining)); 87 } 88 encode_varint(len as u64, buf); 89 self.encode_raw(buf); 90 Ok(()) 91 } 92 93 #[cfg(feature = "std")] 94 /// Encodes the message with a length-delimiter to a newly allocated buffer. encode_length_delimited_to_vec(&self) -> Vec<u8> where Self: Sized,95 fn encode_length_delimited_to_vec(&self) -> Vec<u8> 96 where 97 Self: Sized, 98 { 99 let len = self.encoded_len(); 100 let mut buf = Vec::with_capacity(len + encoded_len_varint(len as u64)); 101 102 encode_varint(len as u64, &mut buf); 103 self.encode_raw(&mut buf); 104 buf 105 } 106 107 /// Decodes an instance of the message from a buffer. 108 /// 109 /// The entire buffer will be consumed. decode<B>(mut buf: B) -> Result<Self, DecodeError> where B: Buf, Self: Default,110 fn decode<B>(mut buf: B) -> Result<Self, DecodeError> 111 where 112 B: Buf, 113 Self: Default, 114 { 115 let mut message = Self::default(); 116 Self::merge(&mut message, &mut buf).map(|_| message) 117 } 118 119 /// Decodes a length-delimited instance of the message from the buffer. decode_length_delimited<B>(buf: B) -> Result<Self, DecodeError> where B: Buf, Self: Default,120 fn decode_length_delimited<B>(buf: B) -> Result<Self, DecodeError> 121 where 122 B: Buf, 123 Self: Default, 124 { 125 let mut message = Self::default(); 126 message.merge_length_delimited(buf)?; 127 Ok(message) 128 } 129 130 /// Decodes an instance of the message from a buffer, and merges it into `self`. 131 /// 132 /// The entire buffer will be consumed. merge<B>(&mut self, mut buf: B) -> Result<(), DecodeError> where B: Buf, Self: Sized,133 fn merge<B>(&mut self, mut buf: B) -> Result<(), DecodeError> 134 where 135 B: Buf, 136 Self: Sized, 137 { 138 let ctx = DecodeContext::default(); 139 while buf.has_remaining() { 140 let (tag, wire_type) = decode_key(&mut buf)?; 141 self.merge_field(tag, wire_type, &mut buf, ctx.clone())?; 142 } 143 Ok(()) 144 } 145 146 /// Decodes a length-delimited instance of the message from buffer, and 147 /// merges it into `self`. merge_length_delimited<B>(&mut self, mut buf: B) -> Result<(), DecodeError> where B: Buf, Self: Sized,148 fn merge_length_delimited<B>(&mut self, mut buf: B) -> Result<(), DecodeError> 149 where 150 B: Buf, 151 Self: Sized, 152 { 153 message::merge( 154 WireType::LengthDelimited, 155 self, 156 &mut buf, 157 DecodeContext::default(), 158 ) 159 } 160 161 /// Clears the message, resetting all fields to their default. clear(&mut self)162 fn clear(&mut self); 163 } 164 165 impl<M> Message for Box<M> 166 where 167 M: Message, 168 { encode_raw<B>(&self, buf: &mut B) where B: BufMut,169 fn encode_raw<B>(&self, buf: &mut B) 170 where 171 B: BufMut, 172 { 173 (**self).encode_raw(buf) 174 } merge_field<B>( &mut self, tag: u32, wire_type: WireType, buf: &mut B, ctx: DecodeContext, ) -> Result<(), DecodeError> where B: Buf,175 fn merge_field<B>( 176 &mut self, 177 tag: u32, 178 wire_type: WireType, 179 buf: &mut B, 180 ctx: DecodeContext, 181 ) -> Result<(), DecodeError> 182 where 183 B: Buf, 184 { 185 (**self).merge_field(tag, wire_type, buf, ctx) 186 } encoded_len(&self) -> usize187 fn encoded_len(&self) -> usize { 188 (**self).encoded_len() 189 } clear(&mut self)190 fn clear(&mut self) { 191 (**self).clear() 192 } 193 } 194 195 #[cfg(test)] 196 mod tests { 197 use super::*; 198 199 const _MESSAGE_IS_OBJECT_SAFE: Option<&dyn Message> = None; 200 } 201