Clarify serialization traits interface

5 files changed, 35 insertions, 16 deletions

diff --git a/include/grpc++/impl/call.h b/include/grpc++/impl/call.h
index 94b0f915c6..7a60ec6587 100644
--- a/include/grpc++/impl/call.h
+++ b/include/grpc++/impl/call.h
@@ -98,7 +98,7 @@ class CallOpSendMessage {
   CallOpSendMessage() : send_buf_(nullptr), own_buf_(false) {}
 
   template <class M>
-  bool SendMessage(const M& message) GRPC_MUST_USE_RESULT;
+  Status SendMessage(const M& message) GRPC_MUST_USE_RESULT;
 
  protected:
   void AddOp(grpc_op* ops, size_t* nops) {
@@ -118,7 +118,7 @@ class CallOpSendMessage {
 };
 
 template <class M>
-bool CallOpSendMessage::SendMessage(const M& message) {
+Status CallOpSendMessage::SendMessage(const M& message) {
   return SerializationTraits<M>::Serialize(message, &send_buf_, &own_buf_);
 }
 
diff --git a/include/grpc++/impl/client_unary_call.h b/include/grpc++/impl/client_unary_call.h
index c1832f9eb8..15db89d3f6 100644
--- a/include/grpc++/impl/client_unary_call.h
+++ b/include/grpc++/impl/client_unary_call.h
@@ -56,11 +56,11 @@ Status BlockingUnaryCall(ChannelInterface* channel, const RpcMethod& method,
   CallOpSet<CallOpSendInitialMetadata, CallOpSendMessage,
             CallOpRecvInitialMetadata, CallOpRecvMessage<OutputMessage>,
             CallOpClientSendClose, CallOpClientRecvStatus> ops;
-  Status status;
-  ops.SendInitialMetadata(context->send_initial_metadata_);
-  if (!ops.SendMessage(request)) {
-    return Status(INVALID_ARGUMENT, "Failed to serialize message");
+  Status status = ops.SendMessage(request);
+  if (!status.IsOk()) {
+    return status;
   }
+  ops.SendInitialMetadata(context->send_initial_metadata_);
   ops.RecvInitialMetadata(context);
   ops.RecvMessage(result);
   ops.ClientSendClose();
diff --git a/include/grpc++/impl/proto_utils.h b/include/grpc++/impl/proto_utils.h
index bf82f2b23d..3097a8da5a 100644
--- a/include/grpc++/impl/proto_utils.h
+++ b/include/grpc++/impl/proto_utils.h
@@ -47,8 +47,8 @@ namespace grpc {
 // Serialize the msg into a buffer created inside the function. The caller
 // should destroy the returned buffer when done with it. If serialization fails,
 // false is returned and buffer is left unchanged.
-bool SerializeProto(const grpc::protobuf::Message& msg,
-                    grpc_byte_buffer** buffer);
+Status SerializeProto(const grpc::protobuf::Message& msg,
+                      grpc_byte_buffer** buffer);
 
 // The caller keeps ownership of buffer and msg.
 Status DeserializeProto(grpc_byte_buffer* buffer, grpc::protobuf::Message* msg,
@@ -58,8 +58,8 @@ template <class T>
 class SerializationTraits<T, typename std::enable_if<std::is_base_of<
                                  grpc::protobuf::Message, T>::value>::type> {
  public:
-  static bool Serialize(const grpc::protobuf::Message& msg,
-                        grpc_byte_buffer** buffer, bool* own_buffer) {
+  static Status Serialize(const grpc::protobuf::Message& msg,
+                          grpc_byte_buffer** buffer, bool* own_buffer) {
     *own_buffer = true;
     return SerializeProto(msg, buffer);
   }
diff --git a/include/grpc++/impl/rpc_service_method.h b/include/grpc++/impl/rpc_service_method.h
index 1bf39fca3b..a5e25f9651 100644
--- a/include/grpc++/impl/rpc_service_method.h
+++ b/include/grpc++/impl/rpc_service_method.h
@@ -94,9 +94,7 @@ class RpcMethodHandler : public MethodHandler {
               CallOpServerSendStatus> ops;
     ops.SendInitialMetadata(param.server_context->initial_metadata_);
     if (status.IsOk()) {
-      if (!ops.SendMessage(rsp)) {
-        status = Status(INTERNAL, "Failed to serialize response");
-      }
+      status = ops.SendMessage(rsp);
     }
     ops.ServerSendStatus(param.server_context->trailing_metadata_, status);
     param.call->PerformOps(&ops);
@@ -131,9 +129,7 @@ class ClientStreamingHandler : public MethodHandler {
               CallOpServerSendStatus> ops;
     ops.SendInitialMetadata(param.server_context->initial_metadata_);
     if (status.IsOk()) {
-      if (!ops.SendMessage(rsp)) {
-        status = Status(INTERNAL, "Failed to serialize response");
-      }
+      status = ops.SendMessage(rsp);
     }
     ops.ServerSendStatus(param.server_context->trailing_metadata_, status);
     param.call->PerformOps(&ops);
diff --git a/include/grpc++/impl/serialization_traits.h b/include/grpc++/impl/serialization_traits.h
index e4f086e08d..ad61dc2f6a 100644
--- a/include/grpc++/impl/serialization_traits.h
+++ b/include/grpc++/impl/serialization_traits.h
@@ -38,6 +38,29 @@ struct grpc_byte_buffer;
 
 namespace grpc {
 
+/// Defines how to serialize and deserialize some type.
+/// 
+/// Used for hooking different message serialization API's into GRPC.
+/// Each SerializationTraits implementation must provide the following
+/// functions:
+///   static Status Serialize(const Message& msg,
+///                           grpc_byte_buffer** buffer, 
+//                            bool* own_buffer);
+///   static Status Deserialize(grpc_byte_buffer* buffer,
+///                             Message* msg,
+///                             int max_message_size);
+///
+/// Serialize is required to convert message to a grpc_byte_buffer, and
+/// to store a pointer to that byte buffer at *buffer. *own_buffer should
+/// be set to true if the caller owns said byte buffer, or false if
+/// ownership is retained elsewhere.
+///
+/// Deserialize is required to convert buffer into the message stored at
+/// msg. max_message_size is passed in as a bound on the maximum number of
+/// message bytes Deserialize should accept.
+///
+/// Both functions return a Status, allowing them to explain what went 
+/// wrong if required.
 template <class Message,
           class UnusedButHereForPartialTemplateSpecialization = void>
 class SerializationTraits;