video_in_hal/otherservice/rpc_library/library/include/other_service/rpc.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file rpc.h
  19  * @brief \~english RPC library --API define header file
  20  */
  21 /** @addtogroup BaseSystem
  22  *  @{
  23  */
  24 /** @addtogroup other_service
  25  *  @ingroup BaseSystem
  26  *  @{
  27  */
  28 /** @addtogroup rpc_library
  29  *  @ingroup other_service
  30  *  @{
  31  */
  32 #ifndef OTHERSERVICE_RPC_H_  // NOLINT(build/header_guard)
  33 #define OTHERSERVICE_RPC_H_  // NOLINT(build/header_guard)
  34
  35 #include <stdio.h>
  36 #include <unistd.h>
  37
  38 #include <other_service/rpc_id.h>
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /**
  45 *   @brief \~english RPC_ID max number
  46 */
  47 #define RPC_MAX_THREADS_IN_PROCESS 64
  48
  49 /** @brief \~english fd max number in one process.
  50  *  0  = main/sub thread communication pipe fd.
  51  *  1  =  inotify() process listen fd.
  52  *  2~129  =  even num : API request data socket.
  53  *  odd num :  secure stream socket.
  54  *         */
  55 #define RPC_MAX_FD_IN_PROCESS 130
  56
  57
  58 #define RPC_MAX_API_ARG_NUM 8
  59 ///< \~english API call parameter max num
  60
  61
  62 #define RPC_MAX_API_ARG_SIZE 1024
  63 ///< \~english API call one parameter max byte
  64
  65 #define RPC_MAX_API_ARG_TOTAL_SIZE 1500
  66 ///< \~english API call all parameter max byte
  67
  68 #define RPC_MAX_APICALL_QUEUE 16
  69 ///< \~english API call max queue num
  70
  71 #define RPC_NO_PORT 0
  72 ///< \~english invalid port num
  73
  74 /** @brief \~english RPC library function return value
  75  */
  76 enum rpc_result {  // NOLINT (readability/nolint)
  77   RPC_OK = 0,  ///< \~english ok
  78   RPC_ERR_No_Response = 0x8fff0000,   ///< \~english has no response
  79   RPC_ERR_Timeout,   ///< \~english timeout
  80   RPC_ERR_Busy,  ///< \~english busy
  81   RPC_ERR_API_Error,  ///< \~english API error
  82   RPC_ERR_API_Fatal,  ///< \~english API fatal
  83   RPC_ERR_Fatal,   ///< \~english fatal
  84   RPC_ERR_Configuration,  ///< \~english configuration
  85   RPC_ERR_Server_DeadLock,  ///< \~english server deadlock
  86   RPC_ERR_Server_Finish,   ///< \~english server finish
  87   RPC_ERR_Reject_connect,   ///< \~english  reject connect
  88 };
  89 /** @brief \~english RPC library function return type
  90  *         @see rpc_result
  91  *         */
  92 typedef INT32 RPC_Result;
  93
  94 /** @brief \~english RPC ID
  95  *
  96  */
  97 typedef UINT32 RPC_ID;
  98
  99 #define RPC_NO_ID RPC_NO_PORT
 100 ///< \~english The ID when destination is invalid
 101
 102 #define RPC_SELF_ID RPC_NO_PORT
 103 ///< \~english The ID when destination is self
 104
 105 /** @brief \~english The ID when destination is any
 106  *         */
 107 #define RPC_ANY_ID RPC_NO_PORT
 108
 109
 110 typedef RPC_Result (*RPC_dispatch_func_t)(UINT16 api_num,
 111             const char *args_string,
 112             unsigned int args_size,
 113             char **ret_string,
 114             unsigned int *ret_bytes);
 115
 116 #ifdef RPC_DISPATCH_FUNC
 117 #error "Please include <rpc.h> before \"*_srvr.h\"."
 118 #else /* !RPC_DISPATCH_FUNC */
 119 #define RPC_DISPATCH_FUNC NULL
 120 #endif /* !RPC_DISPATCH_FUNC */
 121
 122 /* RPC Library Start Function Macro */
 123 /////////////////////////////////////////////////////////////////////////////////////
 124 /// \ingroup RPC_START_SERVER
 125 /// \~english @par Brief
 126 ///     server start(certification of the client by UID)
 127 /// \~english @param [in] ID
 128 ///     RPC_ID - program's RPC_ID
 129 /// \~english @retval RPC_OK Normal End
 130 /// \~english @retval RPC_ERR_Fatal Fatal Error
 131 /// \~english @par Prerequisite
 132 ///     None
 133 /// \~english @par Change of internal state
 134 ///     None
 135 /// \~english @par Conditions of processing failure
 136 ///       - Case of an input parameter error
 137 ///       - Case of fail to information generation
 138 ///       - When RPC_start has already been issued
 139 ///       - Case of space reservation fails
 140 ///       - Case of socket generation fails
 141 ///       - Case of socket allocation fails
 142 ///       - Case of creating a pipe fails
 143 ///         - RPC_ERR_Fatal
 144 /// \~english @par Classification
 145 ///     Public
 146 /// \~english @par Type
 147 ///     Sync Only
 148 /// \~english @par Detail
 149 ///       - Used when the server program of RPC-API performs RPC library use start processing
 150 ///       - ID specifies a symbol in the form of XXX_RPC_ID defined by rpc_id.h
 151 ///       - Only one server program is permitted per thread
 152 ///       - When the server program calls the API as a client of another server,
 153 ///         it only needs to call RPC_START_SERVER, there is no need to call RPC_START_CLIENT
 154 /// \~english @see RPC_start, RPC_end
 155 ////////////////////////////////////////////////////////////////////////////////////
 156 #define RPC_START_SERVER(ID) RPC_start((ID), RPC_DISPATCH_FUNC, NULL, NO_SECURE_CHECK)
 157
 158 /////////////////////////////////////////////////////////////////////////////////////
 159 /// \ingroup RPC_START_SECURE_SERVER
 160 /// \~english @par Brief
 161 ///     server start(certification of the client by UID)
 162 /// \~english @param [in] ID
 163 ///     RPC_ID - program's RPC_ID
 164 /// \~english @retval RPC_OK Normal End
 165 /// \~english @retval RPC_ERR_Fatal Fatal Error
 166 /// \~english @par Prerequisite
 167 ///     None
 168 /// \~english @par Change of internal state
 169 ///     None
 170 /// \~english @par Conditions of processing failure
 171 ///       - Case of an input parameter error
 172 ///       - Case of fail to information generation
 173 ///       - When RPC_start has already been issued
 174 ///       - Case of space reservation fails
 175 ///       - Case of socket generation fails
 176 ///       - Case of socket allocation fails
 177 ///       - Case of creating a pipe fails
 178 ///         - RPC_ERR_Fatal
 179 /// \~english @par Classification
 180 ///     Public
 181 /// \~english @par Type
 182 ///     Sync Only
 183 /// \~english @par Detail
 184 ///       - Used when the server program of RPC-API performs RPC library use start processing
 185 ///       - ID specifies a symbol in the form of XXX_RPC_ID defined by rpc_id.h
 186 ///       - Only one server program is permitted per thread
 187 ///       - When the server program calls the API as a client of another server,
 188 ///         it only needs to call RPC_START_SERVER, there is no need to call RPC_START_CLIENT
 189 /// \~english @see RPC_start, RPC_end
 190 ////////////////////////////////////////////////////////////////////////////////////
 191 #define RPC_START_SECURE_SERVER(ID) RPC_start((ID), RPC_DISPATCH_FUNC, NULL, NEED_SECURE_CHECK)
 192
 193 /////////////////////////////////////////////////////////////////////////////////////
 194 /// \ingroup RPC_START_CLIENT
 195 /// \~english @par Brief
 196 ///     client start
 197 /// \~english @param [out] pID
 198 ///     RPC_ID * - auto allocated program's RPC_ID
 199 /// \~english @retval RPC_OK Normal End
 200 /// \~english @retval RPC_ERR_Fatal Fatal Error
 201 /// \~english @par Prerequisite
 202 ///     None
 203 /// \~english @par Change of internal state
 204 ///     None
 205 /// \~english @par Conditions of processing failure
 206 ///     - input parameter error
 207 ///     - Unable to get the rpc lib info for the self-thread.
 208 ///     - Memory allocation fail for id info.
 209 ///     - Socket generation fail.
 210 ///     - Socket allocation fail.
 211 ///     - Unable to get the socket name.
 212 ///         - RPC_ERR_Fatal
 213 /// \~english @par Classification
 214 ///     Public
 215 /// \~english @par Type
 216 ///     Sync Only
 217 /// \~english @par Detail
 218 ///     - This macro supports only client function of RPC library.
 219 ///     - Run the start processing by using this macro only when the APIs provided by the other program are called.
 220 /// \~english @see RPC_start, RPC_end
 221 ////////////////////////////////////////////////////////////////////////////////////
 222 #define RPC_START_CLIENT(pID) RPC_start((UINT16)RPC_NO_ID, NULL, (pID), NO_SECURE_CHECK)
 223 //!< \~english client start
 224
 225 /* Client authentication by registering the server's UID list */
 226 #define NEED_SECURE_CHECK 1  ///< \~english  has secure check
 227 #define NO_SECURE_CHECK 0  ///< \~english  has no secure check
 228
 229 /* Setting whether to register UID list of server */
 230 #define REGISTERED 1  ///< \~english registered
 231 #define NO_REGISTERED 0  ///< \~english not registered
 232
 233 /* API Function Prototypes in the RPC Library */
 234 RPC_Result RPC_start(RPC_ID id, RPC_dispatch_func_t func, RPC_ID *pID, INT32 secure_check);  // NOLINT (readability/nolint)
 235
 236 /////////////////////////////////////////////////////////////////////////////////////
 237 /// \ingroup RPC_get_fd
 238 /// \~english @par Brief
 239 ///     Get the file descriptor to judge whether there is the request of RPC-API call or not.
 240 /// \~english @param [in] id
 241 ///     RPC_ID - server program's RPC_ID
 242 /// \~english @param [out] fd
 243 ///     int * - area for fd
 244 /// \~english @retval RPC_OK Normal End
 245 /// \~english @retval RPC_ERR_Fatal Fatal Error
 246 /// \~english @par Prerequisite
 247 ///     RPC_START_SERVER or RPC_START_SECURE_SERVER is already called.
 248 /// \~english @par Change of internal state
 249 ///     None
 250 /// \~english @par Conditions of processing failure
 251 ///     - Argument(id) is RPC_NO_ID.
 252 ///     - Argument(fd) is NULL.
 253 ///     - Unable to get the rpc lib info for the self-thread.
 254 ///     - RPC sub thread doesn't exist.
 255 ///       - RPC_ERR_Fatal
 256 /// \~english @par Classification
 257 ///     Public
 258 /// \~english @par Type
 259 ///     Sync Only
 260 /// \~english @par Detail
 261 ///     - This function returns the fd(file descriptor) to judge whether there is the request to server.
 262 ///     - Return value(fd) is used only for poll function or select function parameter.
 263 ///     - Usage
 264 ///       - To get fd from this function.
 265 ///       - Wait for the data to use poll function or select function.
 266 ///       - After that, call RPC_process_API_request function.
 267 ///       - As a result, the API call request from client is done(that is, run the server API).
 268 /// \~english @see None
 269 ////////////////////////////////////////////////////////////////////////////////////
 270 RPC_Result RPC_get_fd(RPC_ID id, int *fd);  // NOLINT (readability/nolint)
 271
 272 /////////////////////////////////////////////////////////////////////////////////////
 273 /// \ingroup RPC_process_API_request
 274 /// \~english @par Brief
 275 ///     Run the processing of RPC-API call
 276 /// \~english @param [in] id
 277 ///     RPC_ID - server program's RPC_ID
 278 /// \~english @retval RPC_OK Normal End
 279 /// \~english @retval RPC_ERR_Fatal Fatal Error
 280 /// \~english @par Prerequisite
 281 ///     RPC_START_SERVER or RPC_START_SECURE_SERVER is already called.
 282 /// \~english @par Change of internal state
 283 ///     None
 284 /// \~english @par Conditions of processing failure
 285 ///     - Argument(id) is RPC_NO_ID.
 286 ///     - Unable to get the rpc lib info for the self-thread.
 287 ///     - RPC sub thread doesn't exist.
 288 ///     - fail to send UDP packet.
 289 ///     - API processing from the client returns the error.
 290 ///       - RPC_ERR_Fatal
 291 /// \~english @par Classification
 292 ///     Public
 293 /// \~english @par Type
 294 ///     Sync Only
 295 /// \~english @par Detail
 296 ///     - Process all the queued API running requests from the client.
 297 ///     - API function of server program is called in this function.
 298 ///     - If there are no requests to run API, this function doesn't wait and return immediately.
 299 /// \~english @see None
 300 ////////////////////////////////////////////////////////////////////////////////////
 301 RPC_Result RPC_process_API_request(RPC_ID id);  // NOLINT (readability/nolint)
 302
 303 /////////////////////////////////////////////////////////////////////////////////////
 304 /// \ingroup RPC_end
 305 /// \~english @par Brief
 306 ///     End processing of RPC library.
 307 /// \~english @param [in] id
 308 ///     RPC_ID - program's RPC_ID
 309 /// \~english @retval None
 310 /// \~english @par Prerequisite
 311 ///     RPC_START_SERVER or RPC_START_SECURE_SERVER or RPC_START_CLIENT is already called.
 312 /// \~english @par Change of internal state
 313 ///     None
 314 /// \~english @par Conditions of processing failure
 315 ///     None
 316 /// \~english @par Classification
 317 ///     Public
 318 /// \~english @par Type
 319 ///     Sync Only
 320 /// \~english @par Detail
 321 ///     - End processing(socket close and memory release etc) is done.
 322 ///     - When there are no more program that uses RPC_ID, RPC sub thread started by RPC_start will be ended.
 323 ///     - Need to call this function before the program is ended.
 324 ///     - Need to call this function from which the thread called RPC_start.
 325 ///     - Nothing is done when incorrect or no more used RPC_ID is designated.
 326 /// \~english @see None
 327 ////////////////////////////////////////////////////////////////////////////////////
 328 void RPC_end(RPC_ID id);  // NOLINT (readability/nolint)
 329
 330 ////////////////////////////////////////////////////////////////////////////////
 331 /// \ingroup RPC_end_all
 332 /// \~english @par Brief
 333 ///     End processing of RPC library(forcing to clean up).
 334 /// \~english @par Prerequisite
 335 ///       - None
 336 /// \~english @par Change of internal state
 337 ///       - None
 338 /// \~english @par Conditions of processing failure
 339 ///       - None
 340 /// \~english @par Classification
 341 ///       Public
 342 /// \~english @par Type
 343 ///       Sync Only
 344 /// \~english @par Detail
 345 ///       Delete the socket files created in process for communication. /n
 346 ///       The program which use RPC library must call RPC_end() to free resource, /n
 347 ///       This API is used for insurance processing when socket file's link lost. /n
 348 ///       1,Before process ends, call this API. /n
 349 ///         When process is ending, auto running socket's close and memory free is not work. /n
 350 ///       2,After called this API, all the RPC's process(both server and client) become to useless. /n
 351 ///         Even if after called this API, call RPC_START to repair it also can't make sure to active. /n
 352 ///       RPC library which use Unix autobind is nothing to do. /n
 353 /// \~english @see None
 354 ////////////////////////////////////////////////////////////////////////////////
 355 void RPC_end_all(void);  // NOLINT (readability/nolint)
 356
 357 /////////////////////////////////////////////////////////////////////////////////////
 358 /// \ingroup RPC_set_API_timeout
 359 /// \~english @par Brief
 360 ///     Set timeout time for server side API processing time
 361 /// \~english @param [in] sec
 362 ///     INT32 - timeout time
 363 /// \~english @retval RPC_OK Normal End
 364 /// \~english @retval RPC_ERR_Fatal Fatal Error
 365 /// \~english @retval RPC_ERR_Configuration Argument is out of range
 366 /// \~english @par Prerequisite
 367 ///     RPC_START_SERVER or RPC_START_SECURE_SERVER is already called.
 368 /// \~english @par Change of internal state
 369 ///     None
 370 /// \~english @par Conditions of processing failure
 371 ///     - Unable to get the rpc lib info for the self-thread.
 372 ///     - Server id info doesn't exist.
 373 ///     - Info for API call reception processing doesn't exist.
 374 ///       - RPC_ERR_Fatal
 375 ///     - The value of the argument(sec) is out of range.
 376 ///       - RPC_ERR_Configuration
 377 /// \~english @par Classification
 378 ///     Public
 379 /// \~english @par Type
 380 ///     Sync Only
 381 /// \~english @par Detail
 382 ///     None
 383 /// \~english @see None
 384 ////////////////////////////////////////////////////////////////////////////////////
 385 RPC_Result RPC_set_API_timeout(INT32 sec);  // NOLINT (readability/nolint)
 386
 387
 388 ////////////////////////////////////////////////////////////////////////////////
 389 /// \ingroup RPC_is_server_ready
 390 /// \~english @par Brief
 391 ///       Return RPC server's status
 392 /// \~english @param [in] id
 393 ///       RPC_ID  -  server program's RPC_ID
 394 ///
 395 /// \~english @retval RPC_OK : Success
 396 /// \~english @retval RPC_ERR_No_Response : No response
 397 ///
 398 /// \~english @par Prerequisite
 399 ///       - None
 400 /// \~english @par Change of internal state
 401 ///       - None
 402 /// \~english @par Conditions of processing failure
 403 ///       - None
 404 /// \~english @par Classification
 405 ///       Public
 406 /// \~english @par Type
 407 ///       Sync Only
 408 /// \~english @par Detail
 409 ///       return the server's work status.
 410 /// \~english @see None
 411 ////////////////////////////////////////////////////////////////////////////////
 412 RPC_Result RPC_is_server_ready(RPC_ID id);  // NOLINT (readability/nolint)
 413
 414 /////////////////////////////////////////////////////////////////////////////////////
 415 /// \ingroup RPC_regist_credential
 416 /// \~english @par Brief
 417 ///     Register UID and GID list
 418 /// \~english @param [in] uid_num
 419 ///     int - UID number to regist(number of elements of UID list)
 420 /// \~english @param [in] uid_list
 421 ///     uid_t* - head pointer of UID list
 422 /// \~english @param [in] gid_num
 423 ///     int - GID number to regist(number of elements of GID list)
 424 /// \~english @param [in] uid_list
 425 ///     gid_t* - head pointer of GID list
 426 /// \~english @retval RPC_OK Normal End
 427 /// \~english @retval RPC_ERR_Fatal Fatal Error
 428 /// \~english @retval RPC_ERR_Configuration Argument is out of range
 429 /// \~english @par Prerequisite
 430 ///     RPC_START_SECURE_SERVER is already called.
 431 /// \~english @par Change of internal state
 432 ///     None
 433 /// \~english @par Conditions of processing failure
 434 ///     - Unable to get the rpc lib info for the self-thread.
 435 ///     - Server id info doesn't exist.
 436 ///     - Info for API call reception processing doesn't exist.
 437 ///     - Arguments(client_uid and client_gid) are NULL.
 438 ///     - Client authentication check is not necessary.
 439 ///     - Authentication info is already registered.
 440 ///     - Memory allocation fail for UID and GID lists.
 441 ///       - RPC_ERR_Fatal
 442 ///     - Values of Arguments(uid_num and gid_num) are out of range.
 443 ///       - RPC_ERR_Configuration
 444 /// \~english @par Classification
 445 ///     Public
 446 /// \~english @par Type
 447 ///     Sync Only
 448 /// \~english @par Detail
 449 ///     - Register the UID and GID lists acceptable by the RPC server.
 450 ///     - If RPC_START_SECURE_SERVER is not called, this function returns the error.
 451 /// \~english @see None
 452 ////////////////////////////////////////////////////////////////////////////////////
 453 RPC_Result RPC_regist_credential(int uid_num, uid_t *uid_list, int gid_num, gid_t *gid_list);  // NOLINT (readability/nolint)
 454
 455 /////////////////////////////////////////////////////////////////////////////////////
 456 /// \ingroup RPC_get_client_credential
 457 /// \~english @par Brief
 458 ///     Get UID and GID of client that requested to run APIs processing
 459 /// \~english @param [out] client_uid
 460 ///     uid_t* - UID of client that requested to run APIs processing
 461 /// \~english @param [out] client_gid
 462 ///     gid_t* - GID of client that requested to run APIs processing
 463 /// \~english @retval RPC_OK Normal End
 464 /// \~english @retval RPC_ERR_Fatal Fatal Error
 465 /// \~english @par Prerequisite
 466 ///     RPC_START_SECURE_SERVER is already called.
 467 /// \~english @par Change of internal state
 468 ///     None
 469 /// \~english @par Conditions of processing failure
 470 ///     - Server id info doesn't exist.
 471 ///     - Info for API call reception processing doesn't exist.
 472 ///     - Arguments(client_uid and client_gid) are NULL.
 473 ///     - Client authentication check is not necessary.
 474 ///     - There are no running clients.
 475 ///     - Info for the running client is not applicable.
 476 ///       - RPC_ERR_Fatal
 477 /// \~english @par Classification
 478 ///     Public
 479 /// \~english @par Type
 480 ///     Sync Only
 481 /// \~english @par Detail
 482 ///     - This function is to get UID and GID of client that requested to run APIs processing.
 483 ///     - If RPC_START_SECURE_SERVER is not called, this function returns the error.
 484 ///     - If the running client doesn't exist, this function returns the error.
 485 /// \~english @see None
 486 ////////////////////////////////////////////////////////////////////////////////////
 487 RPC_Result RPC_get_client_credential(uid_t *client_uid, gid_t *client_gid);  // NOLINT (readability/nolint)
 488
 489 /*
 490  * The following are only used in stub files
 491  */
 492 #define RPC_RETCODE_LEN 9
 493
 494 #define RPC_MARSHALL_FLAG_BITS_CODE 12
 495 #define RPC_MARSHALL_FLAG_BITS_IS_VARARRAY 1
 496 #define RPC_MARSHALL_FLAG_BITS_IS_POINTER 1
 497 #define RPC_MARSHALL_FLAG_BITS_IN_OUT 2
 498
 499 /** @brief \~english  APIcall property stored struct
 500  *
 501  */
 502 typedef union {
 503   UINT32 all;  ///< \~english all property
 504   struct {
 505     unsigned int code: RPC_MARSHALL_FLAG_BITS_CODE;   ///< \~english value type
 506     /** @brief \~english  vararray or not
 507      *
 508      */
 509     unsigned int is_vararray: RPC_MARSHALL_FLAG_BITS_IS_VARARRAY;
 510     /** @brief \~english  pointer or not
 511      *
 512      */
 513     unsigned int is_pointer: RPC_MARSHALL_FLAG_BITS_IS_POINTER;
 514     /** @brief \~english  in/out parameter property
 515      *
 516      */
 517     unsigned int in_out: RPC_MARSHALL_FLAG_BITS_IN_OUT;
 518     /** @brief \~english  string or user define type byte num.other is 0
 519      *
 520      */
 521     UINT16 bytes;
 522   } bits;   ///< \~english variable properties
 523 } RPC_marshall_flag;
 524
 525 /////////////////////////////////////////////////////////////////////////////////////
 526 /// \ingroup RPC_API_call
 527 /// \~english @par brief
 528 ///     API call execution function (client)
 529 /// \~english @param [in] id
 530 ///     RPC_ID - RPC_ID of server program
 531 /// \~english @param [in] api_num
 532 ///     UINT16 - Request API number
 533 /// \~english @param [in] args_string
 534 ///     const char* - Argument string
 535 /// \~english @param [in] args_size
 536 ///     unsigned int - Argument string length
 537 /// \~english @param [out] ret_string
 538 ///     char** - Process result string
 539 /// \~english @param [out] ret_size
 540 ///     unsigned int* - Process result string length
 541 /// \~english @retval RPC_OK Normal End
 542 /// \~english @retval RPC_ERR_Fatal Fatal error
 543 /// \~english @retval RPC_ERR_No_Response No response
 544 /// \~english @retval RPC_ERR_Busy API call queue overflow
 545 /// \~english @retval RPC_ERR_Server_DeadLock RPC server deadlock
 546 /// \~english @retval RPC_ERR_Reject_connect The RPC server does not allow communication
 547 /// \~english @par Prerequisite
 548 ///     The RPC server is running.
 549 /// \~english @par Change of internal state
 550 ///     None
 551 /// \~english @par Conditions of processing failure
 552 ///     - Acquisition of rpc library information for self thread fails
 553 ///     - Generation of self-thread rpc library information fails
 554 ///     - The RPC ID information does not exist
 555 ///     - Failed to receive data from the server at initial authentication
 556 ///     - Analysis of received data failed during initial authentication
 557 ///     - Commands not expected to be received during initial authentication
 558 ///     - Server response when initial authentication is API call error
 559 ///     - Failed to receive data from the server at API processing request
 560 ///     - Analysis of received data failed during API processing request
 561 ///     - Commands not expected to be received during API processing request
 562 ///     - Server response when API processing request is API call error
 563 ///     - Error in server response other than deadlock when processing results are received
 564 ///     - Server shut down
 565 ///         - RPC_ERR_Fatal
 566 ///     - UDP packet transmission fails at initial authentication
 567 ///     - A timeout occurred in response from the server during initial authentication
 568 ///     - UDP packet transmission failed at API processing request
 569 ///     - A timeout occurred in response from the server during API processing request
 570 ///         - RPC_ERR_No_Response
 571 ///     - Server response when initial authentication is API call queue overflow
 572 ///     - Server response when API processing request is API call queue overflow
 573 ///         - RPC_ERR_Busy
 574 ///     - When the server response is deadlocked on initial authentication
 575 ///     - When the server response is deadlocked on API processing request
 576 ///     - Server response is deadlocked when processing result is received
 577 ///         - RPC_ERR_Server_DeadLock
 578 ///     - Server response is not authenticated at initial authentication
 579 ///         - RPC_ERR_Reject_connect
 580 /// \~english @par Classification
 581 ///     Public
 582 /// \~english @par Type
 583 ///     Sync Only
 584 /// \~english @par Detail
 585 ///     - Request execution of RPC-API from the client side.
 586 ///     - However, since this API is called from the automatically generated code, it is not used directly by the user.
 587 /// \~english @see None
 588 ////////////////////////////////////////////////////////////////////////////////////
 589 RPC_Result RPC_API_call(RPC_ID id, UINT16 api_num,  // NOLINT (readability/nolint)
 590       const char *args_string, unsigned int args_size,
 591       char **ret_string, unsigned int *ret_size);
 592
 593 /////////////////////////////////////////////////////////////////////////////////////
 594 /// \ingroup RPC_demarshall_arguments
 595 /// \~english @par Brief
 596 ///     Confirm whether the input character string conforms to the prescribed format.
 597 /// \~english @param [in] from
 598 ///     const char * - Input string
 599 /// \~english @param [in] size
 600 ///     unsigned int - Byte length of the input string
 601 /// \~english @param [in] need_alloc
 602 ///     int - Flag whether memory allocation is necessary or not.
 603 /// \~english @param [in] num_args
 604 ///     int - Number of the variable length arguments
 605 /// \~english @param [in] ...
 606 ///     void * - Variable length arguments
 607 /// \~english @retval  0 Normal End
 608 /// \~english @retval -1 Abnormal End
 609 /// \~english @par Prerequisite
 610 ///     None
 611 /// \~english @par Change of internal state
 612 ///     None
 613 /// \~english @par Conditions of processing failure
 614 ///     - Byte length of the input string is 0 bytes or less or larger than 1024 bytes.
 615 ///     - The input character string doesn't conform to the prescribed format.
 616 ///       - -1
 617 /// \~english @par Classification
 618 ///     Public
 619 /// \~english @par Type
 620 ///     Sync Only
 621 /// \~english @par Detail
 622 ///     This function is used in the stub file only and user must not call this function directly.
 623 /// \~english @see RPC_marshall_arguments
 624 ////////////////////////////////////////////////////////////////////////////////////
 625 int RPC_demarshall_arguments(const char *from, unsigned int size,  // NOLINT (readability/nolint)
 626            int need_alloc, int num_args, ...);
 627
 628 /////////////////////////////////////////////////////////////////////////////////////
 629 /// \ingroup RPC_marshall_arguments
 630 /// \~english @par Brief
 631 ///     Collect variable arguments, convert them to a format that matches the receiver's specification,
 632 ///     and stuff them into the message buffer.
 633 /// \~english @param [in] size
 634 ///     unsigned int * - data size after conversion
 635 /// \~english @param [in] dont_marshall_out_args
 636 ///     int - input/output kind(when the argument is a pointer)
 637 /// \~english @param [in] num_args
 638 ///     int - value of variable argument
 639 /// \~english @param [in] ...
 640 ///     void * - variable argument
 641 /// \~english @retval char * Message buffer after conversion
 642 /// \~english @retval NULL   Abnormal
 643 /// \~english @par Prerequisite
 644 ///     None
 645 /// \~english @par Change of internal state
 646 ///     None
 647 /// \~english @par Conditions of processing failure
 648 ///     - When marshall work securing work area fails
 649 ///     - When the specified type size is abnormal
 650 ///     - When securing the area of the message buffer after conversion fails
 651 ///       - NULL
 652 /// \~english @par Classification
 653 ///     Public
 654 /// \~english @par Type
 655 ///     Sync Only
 656 /// \~english @par Detail
 657 ///     This function is used in the stub file for client only and user must not call this function directly.
 658 /// \~english @see RPC_demarshalol_arguments
 659 ////////////////////////////////////////////////////////////////////////////////////
 660 char *RPC_marshall_arguments(unsigned int *size, int dont_marshall_out_args,  // NOLINT (readability/nolint)
 661            int num_args, ...);
 662
 663 /////////////////////////////////////////////////////////////////////////////////////
 664 /// \ingroup RPC_marshall_free
 665 /// \~english @par Brief
 666 ///     Variadic function for memory release
 667 /// \~english @param [in] num
 668 ///     int - number of memory to be released
 669 /// \~english @param [in] ...
 670 ///     void * - allocated memory
 671 /// \~english @retval None
 672 /// \~english @par Prerequisite
 673 ///     None
 674 /// \~english @par Change of internal state
 675 ///     None
 676 /// \~english @par Conditions of processing failure
 677 ///     None
 678 /// \~english @par Classification
 679 ///     Public
 680 /// \~english @par Type
 681 ///     Sync Only
 682 /// \~english @par Detail
 683 ///     - This function is used in the stub file only and user must not call this function directly.
 684 /// \~english @see None
 685 ////////////////////////////////////////////////////////////////////////////////////
 686 void RPC_marshall_free(int num, ...);  // NOLINT (readability/nolint)
 687
 688 /////////////////////////////////////////////////////////////////////////////////////
 689 /// \ingroup RPC_free_return_string
 690 /// \~english @par Brief
 691 ///     release memory allocated during running API call.
 692 /// \~english @param [in] ptr
 693 ///     void * - allocated memory
 694 /// \~english @retval None
 695 /// \~english @par Prerequisite
 696 ///     RPC_API_call is already called.
 697 /// \~english @par Change of internal state
 698 ///     None
 699 /// \~english @par Conditions of processing failure
 700 ///     None
 701 /// \~english @par Classification
 702 ///     Public
 703 /// \~english @par Type
 704 ///     Sync Only
 705 /// \~english @par Detail
 706 ///     - This function is used in the stub file for client only and user must not call this function directly.
 707 /// \~english @see None
 708 ////////////////////////////////////////////////////////////////////////////////////
 709 void RPC_free_return_string(void *ptr);  // NOLINT (readability/nolint)
 710
 711 #ifdef DBG_ENABLE
 712
 713 ////////////////////////////////////////////////////////////////////////////////
 714 /// \ingroup RPC_record_dbg_log
 715 /// \~english @par Brief
 716 ///       RPC-API call process's log
 717 /// \~english @param [in] filename
 718 ///       const char  -  filename's point
 719 /// \~english @param [in] funcname
 720 ///       const char  -  function name's point
 721 /// \~english @param [in] line
 722 ///       int         -  file's line
 723 /// \~english @param [in] apiname
 724 ///       const char  - called API name's point
 725 /// \~english @param [out]
 726 ///
 727 /// \~english @retval 0 : Success
 728 ///
 729 /// \~english @par Prerequisite
 730 ///       - DBG_ENABLE is defined.
 731 /// \~english @par Change of internal state
 732 ///       - None
 733 /// \~english @par Conditions of processing failure
 734 ///       - None
 735 /// \~english @par Classification
 736 ///       Public
 737 /// \~english @par Type
 738 ///       Sync Only
 739 /// \~english @par Detail
 740 ///       Receipt and record the client's filename, function name,
 741 ///       line and called API's function name which called this API.
 742 /// \~english @see None
 743 ////////////////////////////////////////////////////////////////////////////////
 744 int RPC_record_dbg_log(const char *filename, const char *funcname, int line,
 745   const char *apiname);
 746 #endif
 747
 748 #define rpc_malloc malloc
 749 #define rpc_free free
 750
 751 /*
 752  * RPC debug message control
 753  * if set to non-null and some critical information is displayed.
 754  */
 755 extern char *RPC_DEBUG;  // NOLINT (readability/nolint)
 756
 757 /** @}*/  // end of rpc_library
 758 /** @}*/  // end of other_service
 759 /** @}*/  // end of BaseSystem
 760
 761 #ifdef __cplusplus
 762 }
 763 #endif
 764
 765 #endif  // OTHERSERVICE_RPC_H_