documents/RpcMessageFrameFormat.md

   1
   2 ### rpc message frame format
   3
   4 The rpc message format is defined like below.
   5
   6 ```c
   7
   8 #include <stdint.h>
   9
  10 #pragma pack(1)
  11
  12 //function:push (push bytes data to server and put the reference into slot addressed by dest_addr.)
  13 //Explain in C, *dest_addr=&data
  14 struct push_request{
  15     struct{
  16         uint8_t opcode;  // "opcode" identify the type of the request. for push_request,this value is 1
  17         uint8_t id1;
  18         uint16_t id2;
  19     } session;   /* "session" is an identifier established by the client.
  20         The Server MUST reply "session" with the same value in the Response struct for ALL request types */
  21
  22     uint32_t dest_addr;
  23     uint32_t length;
  24     char data[length];
  25 };
  26 struct push_response{
  27     struct{
  28         uint8_t opcode;  // 1
  29         uint8_t id1;
  30         uint16_t id2;
  31     } session;  // MUST be the same as the value of "session" in request
  32 };
  33
  34 //function:pull (pull bytes data refered by the reference in slot addressed by src_addr.)
  35 //Explain in C, return **src_addr
  36 struct pull_request{
  37     struct{
  38         uint8_t opcode;  // 2
  39         uint8_t id1;
  40         uint16_t id2;
  41     } session;
  42     uint32_t src_addr;
  43 };
  44 struct pull_response{
  45     struct{
  46         uint8_t opcode;  // 2
  47         uint8_t id1;
  48         uint16_t id2;
  49     } session;
  50
  51     uint32_t length; // 0XFFFFFFFF(-1) if data can't be transfered,In this case, sizeof(data)==0
  52     char data[length];
  53 };
  54 //function:assign (set slot value.)
  55 //Explain in C, *dest_addr=*src_addr
  56 struct assign_request{
  57     struct{
  58         uint8_t opcode;  // 3
  59         uint8_t id1;
  60         uint16_t id2;
  61     } session;
  62     uint32_t dest_addr;
  63     uint32_t src_addr;
  64 };
  65 struct assign_response{
  66     struct{
  67         uint8_t opcode;  // 3
  68         uint8_t id1;
  69         uint16_t id2;
  70     } session;
  71 };
  72
  73 //function:unlink (set slot to NULL.)
  74 // Explain in C, *dest_addr=NULL
  75 //server may decide if the resources can be free.
  76 struct unlink_request{
  77     struct{
  78         uint8_t opcode;  // 4
  79         uint8_t id1;
  80         uint16_t id2;
  81     } session;
  82     uint32_t dest_addr;
  83 };
  84 struct unlink_response{
  85     struct{
  86         uint8_t opcode;  // 4
  87         uint8_t id1;
  88         uint16_t id2;
  89     } session;
  90 };
  91
  92 //function:call (invoke function stored in func_addr.)
  93 //Explain in C, *dest_addr=(*func_addr)(param1,param2...)
  94 //PxpRpc assume the client always know the definition of the function.
  95 //So wrong parameter may BREAK the PxpRpc connection permanently.
  96 struct call_request{
  97     struct{
  98         uint8_t opcode;  // 5
  99         uint8_t id1;
 100         uint16_t id2;
 101     } session;
 102     uint32_t dest_addr;
 103     uint32_t func_addr;
 104     //parameter
 105     uint32_t param1;
 106     uint64_t param2;
 107     uint32_t etc;
 108 };
 109 struct call_response{
 110     struct{
 111         uint8_t opcode;  // 5
 112         uint8_t id1;
 113         uint16_t id2;
 114     } session;
 115     any returnValue
 116 };
 117 //In general(but not necessary), return value are defined like below.
 118 struct call_response{
 119     struct{
 120         uint8_t opcode;  // 5
 121         uint8_t id1;
 122         uint16_t id2;
 123     } session;
 124     #if FUNCTION_RETURN_32BIT
 125     //function return boolean,int32,float32.
 126     //if function is supposed to return an object,
 127     //returnValue=0 to indicate the sucess(In this case, dest_addr will store the return object),
 128     //returnValue=1 to indicate the fault(In this case, dest_addr will store an Exception).
 129     uint32_t returnValue;
 130     #elif FUNCTION_RETURN_64BIT
 131     //funcion return int64,float64
 132     uint64_t returnValue;
 133     #endif
 134 };
 135
 136 //function:getFunc (get builtin function named by string refered by func_name_addr.)
 137 //Explain in C,*dest_addr=getFunction(*func_name_addr)
 138 //func_name_addr can be a slot where stored the reference to a utf8 encode string pushed previously.
 139 struct getFunc_request{
 140     struct{
 141         uint8_t opcode;  // 6
 142         uint8_t id1;
 143         uint16_t id2;
 144     } session;
 145     uint32_t dest_addr;
 146     uint32_t func_name_addr;
 147 };
 148 struct getFunc_response{
 149     struct{
 150         uint8_t opcode;  // 6
 151         uint8_t id1;
 152         uint16_t id2;
 153     } session;
 154     uint32_t dest_addr; // 0 if function not found
 155 };
 156
 157 //function:close (free the resource and prepare to disconnect)
 158 struct close_request{
 159     struct{
 160         uint8_t opcode;  // 7
 161         uint8_t id1;
 162         uint16_t id2;
 163     } session;
 164 };
 165 //closed, No response.
 166
 167 //function:getInfo (get string encoded in utf8 indicate the information about the server.)
 168 struct getInfo_request{
 169     struct{
 170         uint8_t opcode;  // 8
 171         uint8_t id1;
 172         uint16_t id2;
 173     } session;
 174 };
 175 struct getInfo_response{
 176     struct{
 177         uint8_t opcode;  // 8
 178         uint8_t id1;
 179         uint16_t id2;
 180     } session;
 181     uint32_t length; // 0XFFFFFFFF(-1) if data can't be transfered,In this case, sizeof(data)==0
 182     char data[length];
 183 };
 184 /*
 185 "data" stored the information about the server (as utf8). An example "data" show below
 186 -----------------------------
 187 server name:pxprpc for java
 188 version:1.0
 189 reference slots size:256
 190 -------------------------------
 191 "server name" indicate the server name.
 192 "version" indicate the pxprpc protocol version. Currently only 1.0 is valid.
 193 "reference slots capacity" indicate how many slots can client use. Client should ensure that the slot address is less than this value.
 194 */
 195
 196 /*
 197 the server should take responsibility for the lifecycle manager of the objects referred by references slots.
 198 When an object have no reference refer to, server should free it.
 199 */
 200 ```