README.md

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