1 /* -*- c -*- 2 * virnetprotocol.x: basic protocol for all RPC services. 3 * 4 * Copyright (C) 2006-2012 Red Hat, Inc. 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library. If not, see 18 * <http://www.gnu.org/licenses/>. 19 */ 20 21 %#include "internal.h" 22 %#include "virxdrdefs.h" 23 %#include "virsocket.h" 24 25 /*----- Data types. -----*/ 26 27 /* Initial message size. 28 * When the message payload is larger this initial size will be 29 * quadrupled until the maximum total message size is reached. 30 */ 31 const VIR_NET_MESSAGE_INITIAL = 65536; 32 33 /* 34 * Until we enlarged the message buffers, this was the max 35 * payload size. We need to remember this for compat with 36 * old clients. 37 */ 38 const VIR_NET_MESSAGE_LEGACY_PAYLOAD_MAX = 262120; 39 40 /* Maximum total message size (serialised). */ 41 const VIR_NET_MESSAGE_MAX = 33554432; 42 43 /* Size of struct virNetMessageHeader (serialised)*/ 44 const VIR_NET_MESSAGE_HEADER_MAX = 24; 45 46 /* Size of message payload */ 47 const VIR_NET_MESSAGE_PAYLOAD_MAX = 33554408; 48 49 /* Size of message length field. Not counted in VIR_NET_MESSAGE_MAX 50 * and VIR_NET_MESSAGE_INITIAL. 51 */ 52 const VIR_NET_MESSAGE_LEN_MAX = 4; 53 54 /* Length of long, but not unbounded, strings. 55 * This is an arbitrary limit designed to stop the decoder from trying 56 * to allocate unbounded amounts of memory when fed with a bad message. 57 */ 58 const VIR_NET_MESSAGE_STRING_MAX = 4194304; 59 60 /* Limit on number of File Descriptors allowed to be 61 * passed per message 62 */ 63 const VIR_NET_MESSAGE_NUM_FDS_MAX = 32; 64 65 /* 66 * RPC wire format 67 * 68 * Each message consists of: 69 * 70 * Name | Type | Description 71 * -----------+-----------------------+------------------ 72 * Length | int | Total number of bytes in message _including_ length. 73 * Header | virNetMessageHeader | Control information about procedure call 74 * Payload | - | Variable payload data per procedure 75 * 76 * In header, the 'serial' field varies according to: 77 * 78 * - type == VIR_NET_CALL 79 * * serial is set by client, incrementing by 1 each time 80 * 81 * - type == VIR_NET_REPLY 82 * * serial matches that from the corresponding VIR_NET_CALL 83 * 84 * - type == VIR_NET_MESSAGE 85 * * serial is always zero 86 * 87 * - type == VIR_NET_STREAM 88 * * serial matches that from the corresponding VIR_NET_CALL 89 * 90 * and the 'status' field varies according to: 91 * 92 * - type == VIR_NET_CALL 93 * * VIR_NET_OK always 94 * 95 * - type == VIR_NET_REPLY 96 * * VIR_NET_OK if RPC finished successfully 97 * * VIR_NET_ERROR if something failed 98 * 99 * - type == VIR_NET_MESSAGE 100 * * VIR_NET_OK always 101 * 102 * - type == VIR_NET_STREAM 103 * * VIR_NET_CONTINUE if more data is following 104 * * VIR_NET_OK if stream is complete 105 * * VIR_NET_ERROR 106 * server message: stream had an error 107 * client message: client aborted the stream 108 * 109 * Payload varies according to type and status: 110 * 111 * - type == VIR_NET_CALL 112 * XXX_args for procedure 113 * 114 * - type == VIR_NET_REPLY 115 * * status == VIR_NET_OK 116 * XXX_ret for procedure 117 * * status == VIR_NET_ERROR 118 * remote_error Error information 119 * 120 * - type == VIR_NET_MESSAGE 121 * * status == VIR_NET_OK 122 * XXX_msg for event information 123 * 124 * - type == VIR_NET_STREAM 125 * * status == VIR_NET_CONTINUE 126 * byte[] raw stream data 127 * * status == VIR_NET_ERROR 128 * server message: remote_error error information 129 * client message: <empty> 130 * * status == VIR_NET_OK 131 * <empty> 132 * 133 * - type == VIR_NET_CALL_WITH_FDS 134 * int8 - number of FDs 135 * XXX_args for procedure 136 * 137 * - type == VIR_NET_REPLY_WITH_FDS 138 * int8 - number of FDs 139 * * status == VIR_NET_OK 140 * XXX_ret for procedure 141 * * status == VIR_NET_ERROR 142 * remote_error Error information 143 * 144 * - type == VIR_NET_STREAM_HOLE 145 * * status == VIR_NET_CONTINUE 146 * byte[] hole data 147 * * status == VIR_NET_ERROR 148 * remote_error error information 149 * * status == VIR_NET_OK 150 * <empty> 151 * 152 */ 153 enum virNetMessageType { 154 /* client -> server. args from a method call */ 155 VIR_NET_CALL = 0, 156 /* server -> client. reply/error from a method call */ 157 VIR_NET_REPLY = 1, 158 /* either direction. async notification */ 159 VIR_NET_MESSAGE = 2, 160 /* either direction. stream data packet */ 161 VIR_NET_STREAM = 3, 162 /* client -> server. args from a method call, with passed FDs */ 163 VIR_NET_CALL_WITH_FDS = 4, 164 /* server -> client. reply/error from a method call, with passed FDs */ 165 VIR_NET_REPLY_WITH_FDS = 5, 166 /* either direction, stream hole data packet */ 167 VIR_NET_STREAM_HOLE = 6 168 }; 169 170 enum virNetMessageStatus { 171 /* Status is always VIR_NET_OK for calls. 172 * For replies, indicates no error. 173 */ 174 VIR_NET_OK = 0, 175 176 /* For replies, indicates that an error happened, and a struct 177 * remote_error follows. 178 */ 179 VIR_NET_ERROR = 1, 180 181 /* For streams, indicates that more data is still expected 182 */ 183 VIR_NET_CONTINUE = 2 184 }; 185 186 /* 4 byte length word per header */ 187 const VIR_NET_MESSAGE_HEADER_XDR_LEN = 4; 188 189 struct virNetMessageHeader { 190 unsigned prog; /* Unique ID for the program */ 191 unsigned vers; /* Program version number */ 192 int proc; /* Unique ID for the procedure within the program */ 193 virNetMessageType type; /* Type of message */ 194 unsigned serial; /* Serial number of message. */ 195 virNetMessageStatus status; 196 }; 197 198 /* Error message. See <virterror.h> for explanation of fields. */ 199 200 /* Most of these don't really belong here. There are sadly needed 201 * for wire ABI backwards compatibility with the rather crazy 202 * error struct we previously defined :-( 203 */ 204 205 typedef opaque virNetMessageUUID[VIR_UUID_BUFLEN]; 206 typedef string virNetMessageNonnullString<VIR_NET_MESSAGE_STRING_MAX>; 207 208 /* A long string, which may be NULL. */ 209 typedef virNetMessageNonnullString *virNetMessageString; 210 211 /* A domain which may not be NULL. */ 212 struct virNetMessageNonnullDomain { 213 virNetMessageNonnullString name; 214 virNetMessageUUID uuid; 215 int id; 216 }; 217 218 /* A network which may not be NULL. */ 219 struct virNetMessageNonnullNetwork { 220 virNetMessageNonnullString name; 221 virNetMessageUUID uuid; 222 }; 223 224 225 typedef virNetMessageNonnullDomain *virNetMessageDomain; 226 typedef virNetMessageNonnullNetwork *virNetMessageNetwork; 227 228 /* NB. Fields "code", "domain" and "level" are really enums. The 229 * numeric value should remain compatible between libvirt and 230 * libvirtd. This means, no changing or reordering the enums as 231 * defined in <virterror.h> (but we don't do that anyway, for separate 232 * ABI reasons). 233 */ 234 struct virNetMessageError { 235 int code; 236 int domain; 237 virNetMessageString message; 238 int level; 239 virNetMessageDomain dom; /* unused */ 240 virNetMessageString str1; 241 virNetMessageString str2; 242 virNetMessageString str3; 243 int int1; 244 int int2; 245 virNetMessageNetwork net; /* unused */ 246 }; 247 248 struct virNetStreamHole { 249 hyper length; 250 unsigned int flags; 251 }; 252