Annotation of libaitrpc/inc/aitrpc_cli.h, revision 1.2
1.2 ! misho 1: /*************************************************************************
! 2: * (C) 2015 AITNET ltd - Sofia/Bulgaria - <misho@aitbg.com>
! 3: * by Michael Pounov <misho@openbsd-bg.org>
! 4: *
! 5: * $Author: misho $
! 6: * $Id: aitrpc_cli.h,v 1.1.2.1 2015/07/02 17:52:52 misho Exp $
! 7: *
! 8: **************************************************************************
! 9: The ELWIX and AITNET software is distributed under the following
! 10: terms:
! 11:
! 12: All of the documentation and software included in the ELWIX and AITNET
! 13: Releases is copyrighted by ELWIX - Sofia/Bulgaria <info@elwix.org>
! 14:
! 15: Copyright 2004 - 2015
! 16: by Michael Pounov <misho@elwix.org>. All rights reserved.
! 17:
! 18: Redistribution and use in source and binary forms, with or without
! 19: modification, are permitted provided that the following conditions
! 20: are met:
! 21: 1. Redistributions of source code must retain the above copyright
! 22: notice, this list of conditions and the following disclaimer.
! 23: 2. Redistributions in binary form must reproduce the above copyright
! 24: notice, this list of conditions and the following disclaimer in the
! 25: documentation and/or other materials provided with the distribution.
! 26: 3. All advertising materials mentioning features or use of this software
! 27: must display the following acknowledgement:
! 28: This product includes software developed by Michael Pounov <misho@elwix.org>
! 29: ELWIX - Embedded LightWeight unIX and its contributors.
! 30: 4. Neither the name of AITNET nor the names of its contributors
! 31: may be used to endorse or promote products derived from this software
! 32: without specific prior written permission.
! 33:
! 34: THIS SOFTWARE IS PROVIDED BY AITNET AND CONTRIBUTORS ``AS IS'' AND
! 35: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 36: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 37: ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 38: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 39: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 40: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 41: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 42: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 43: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 44: SUCH DAMAGE.
! 45: */
! 46: #ifndef __AITRPC_CLI_H
! 47: #define __AITRPC_CLI_H
! 48:
! 49:
! 50: #include <aitrpc_pkt.h>
! 51:
! 52:
! 53: /* Network RPC client elements */
! 54:
! 55: typedef struct {
! 56: int cli_id; /* slot id */
! 57: int cli_sock; /* socket fd */
! 58: sockaddr_t cli_sa; /* host address */
! 59: ait_val_t cli_buf; /* network buffer */
! 60:
! 61: array_t *cli_vars; /* function return variables */
! 62:
! 63: void *cli_parent; /* pointer to parent rpc_srv_t for server or to rpc_sess_t for client */
! 64: } rpc_cli_t;
! 65: #define RPC_RETVARS(x) ((x)->cli_vars)
! 66: #define RPC_SRV_SERVER(x) ((rpc_srv_t*) (x)->cli_parent)
! 67: #define RPC_CLI_SESSION(x) ((rpc_sess_t*) (x)->cli_parent)
! 68:
! 69: /* ----------------------------------------------------------------------- */
! 70:
! 71: /* Error support functions */
! 72:
! 73: // rpc_GetErrno() Get error code of last operation
! 74: int rpc_GetErrno();
! 75: // rpc_GetError() Get error text of last operation
! 76: const char *rpc_GetError();
! 77: // rpc_SetErr() Set error to variables for internal use!!!
! 78: void rpc_SetErr(int eno, char *estr, ...);
! 79:
! 80:
! 81: /*
! 82: * rpc_Read() - RPC read operation
! 83: *
! 84: * @sock = socket
! 85: * @type = type of socket
! 86: * @flags = receive flags
! 87: * @sa = check client address, if you use udp protocol
! 88: * @pkt = RPC packet
! 89: * return: -1 error, 0 EOF or or >0 readed bytes into buffer
! 90: */
! 91: ssize_t rpc_Read(int sock, int type, int flags, sockaddr_t * __restrict sa,
! 92: ait_val_t * __restrict pkt);
! 93: /*
! 94: * rpc_Write() - RPC write operation
! 95: *
! 96: * @sock = socket
! 97: * @type = type of socket
! 98: * @flags = send flags
! 99: * @sa = send to client address, if you use udp protocol
! 100: * @pkt = RPC packet
! 101: * @blen = write length
! 102: * return: -1 error, 0 EOF or >0 written bytes into buffer
! 103: */
! 104: ssize_t rpc_Write(int sock, int type, int flags, sockaddr_t * __restrict sa,
! 105: ait_val_t * __restrict pkt, size_t blen);
! 106:
! 107: /*
! 108: * rpc_pktFreeSpace() - Get free space for payload into RPC packet
! 109: *
! 110: * @c = RPC client
! 111: * return: remains free bytes from packet
! 112: */
! 113: size_t rpc_pktFreeSpace(rpc_cli_t * __restrict c);
! 114: /*
! 115: * rpc_chkPktSession() - Check RPC session
! 116: *
! 117: * @p = packet session
! 118: * @s = active session
! 119: * return: -1, 1, 2, 3 are errors or 0 ok
! 120: */
! 121: int rpc_chkPktSession(rpc_sess_t *p, rpc_sess_t *s);
! 122: /*
! 123: * rpc_addPktSession() - Prepare session into network format
! 124: *
! 125: * @p = packet session
! 126: * @s = host session
! 127: * return: -1 error or 0 ok
! 128: */
! 129: int rpc_addPktSession(rpc_sess_t *p, rpc_sess_t *s);
! 130:
! 131: /* CLIENT part of functions */
! 132:
! 133: /*
! 134: * rpc_cli_sendBLOB() - Send BLOB to server
! 135: *
! 136: * @cli = Client instance
! 137: * @var = BLOB variable
! 138: * @data = BLOB data
! 139: * @tout = BLOB live on server timeout in seconds, if =0 default timeout
! 140: * return: -1 error, 0 ok, 1 remote error
! 141: */
! 142: int rpc_cli_sendBLOB(rpc_cli_t * __restrict cli, ait_val_t * __restrict var,
! 143: void * __restrict data, int tout);
! 144: /*
! 145: * rpc_cli_recvBLOB() - Receive BLOB from server
! 146: *
! 147: * @cli = Client instance
! 148: * @var = BLOB variable
! 149: * @data = BLOB data, must be e_free after use!
! 150: * return: -1 error, 0 ok, 1 remote error
! 151: */
! 152: int rpc_cli_recvBLOB(rpc_cli_t * __restrict cli, ait_val_t * __restrict var, void ** __restrict data);
! 153: /*
! 154: * rpc_cli_delBLOB() - Delete BLOB from server
! 155: *
! 156: * @cli = Client instance
! 157: * @var = BLOB variable
! 158: * return: -1 error, 0 ok, 1 remote error
! 159: */
! 160: int rpc_cli_delBLOB(rpc_cli_t * __restrict cli, ait_val_t * __restrict var);
! 161: /*
! 162: * rpc_cli_getBLOB() - Receive BLOB from server and Delete after that.
! 163: *
! 164: * @cli = Client instance
! 165: * @var = BLOB variable
! 166: * @data = BLOB data, must be e_free after use!
! 167: * return: -1 error, 0 ok, >0 remote error
! 168: */
! 169: int rpc_cli_getBLOB(rpc_cli_t * __restrict cli, ait_val_t * __restrict var,
! 170: void ** __restrict data);
! 171:
! 172:
! 173: /* RPC Client side functions */
! 174:
! 175: /*
! 176: * rpc_cli_openClient() - Connect to RPC Server
! 177: *
! 178: * @InstID = InstID for RPC session request
! 179: * @netBuf = Network buffer length (min:512 bytes), if =0 == BUFSIZ (also meaning max RPC packet)
! 180: * @csHost = Host name or IP address for bind server
! 181: * @Port = Port for bind server, if Port == 0 default port is selected
! 182: * @proto = Protocol, if == 0 choose SOCK_STREAM
! 183: * return: NULL == error or !=NULL connection to RPC server established
! 184: */
! 185: rpc_cli_t *rpc_cli_openClient(unsigned char InstID, int netBuf,
! 186: const char *csHost, unsigned short Port, int proto);
! 187: /*
! 188: * rpc_cli_reconnectClient() - Reconnecting client to RPC server
! 189: *
! 190: * @cli = RPC Client session
! 191: * return: -1 error or 0 ok
! 192: */
! 193: int rpc_cli_reconnectClient(rpc_cli_t * __restrict cli);
! 194: /*
! 195: * rpc_cli_closeClient() - Close connection to RPC server and free resources
! 196: *
! 197: * @cli = RPC Client session
! 198: * return: none
! 199: */
! 200: void rpc_cli_closeClient(rpc_cli_t ** __restrict cli);
! 201: /*
! 202: * rpc_pkt_Send() - Send RPC packet
! 203: *
! 204: * @sock = Socket
! 205: * @type = Type of socket
! 206: * @sa = Server address
! 207: * @pkt = RPC packet
! 208: * @len = Length of packet
! 209: * return: -1 error, 0 EOF or >0 sended bytes
! 210: */
! 211: int rpc_pkt_Send(int sock, int type, sockaddr_t * __restrict sa,
! 212: ait_val_t * __restrict pkt, int len);
! 213: /*
! 214: * rpc_pkt_Receive() - Receive RPC packet
! 215: *
! 216: * @sock = Socket
! 217: * @type = Type of socket
! 218: * @sa = Server address
! 219: * @pkt = RPC packet
! 220: * @seq = Signed packet with seq.no
! 221: * return: -1 error, 0 EOF or >0 received bytes
! 222: */
! 223: int rpc_pkt_Receive(int sock, int type, sockaddr_t * __restrict sa,
! 224: ait_val_t * __restrict pkt, int seq);
! 225: /*
! 226: * rpc_pkt_Request() - Build RPC Request packet
! 227: *
! 228: * @pkt = Packet buffer
! 229: * @sess = RPC session info
! 230: * @tag = Function tag for execution
! 231: * @vars = Function argument array of values, may be NULL
! 232: * @noreply = We not want RPC reply
! 233: * @nocrc = Without CRC calculation
! 234: * @seq = Sign packet with seq.no
! 235: * return: -1 error or != -1 prepared bytes into packet
! 236: */
! 237: int rpc_pkt_Request(ait_val_t * __restrict pkt, rpc_sess_t * __restrict sess,
! 238: unsigned short tag, array_t * __restrict vars, int noreply, int nocrc, int seq);
! 239: /*
! 240: * rpc_pkt_Replay() - Decode RPC Replay packet
! 241: *
! 242: * @pkt = Packet buffer
! 243: * @sess = RPC session info, if =NULL don't check session
! 244: * @tag = Function tag, if =CALL_TAG_MAX don't check tag
! 245: * @vars = Function argument array of values, may be NULL
! 246: * @nocrc = Without CRC calculation
! 247: * return: -1 error or != -1 return value from function
! 248: */
! 249: int rpc_pkt_Replay(ait_val_t * __restrict pkt, rpc_sess_t * __restrict sess,
! 250: unsigned short tag, array_t ** __restrict vars, int nocrc);
! 251: /*
! 252: * rpc_cli_execCall() - Execute RPC call
! 253: *
! 254: * @cli = RPC Client session
! 255: * @noreply = We not want RPC reply
! 256: * @tag = Function tag for execution
! 257: * @in_vars = IN function argument array of values, may be NULL
! 258: * @out_vars = OUT returned array of rpc values, if !=NULL must be free after use with ait_freeVars()
! 259: * return: -1 error, 0 ok result or 1 closed rpc connection
! 260: */
! 261: int rpc_cli_execCall(rpc_cli_t *cli, int noreply, unsigned short tag,
! 262: array_t * __restrict in_vars, array_t ** __restrict out_vars);
! 263: /*
! 264: * rpc_cli_freeCall() - Free resouce allocated by RPC call
! 265: *
! 266: * @out_vars = Returned array with variables from RPC call
! 267: * return: none
! 268: */
! 269: void rpc_cli_freeCall(array_t ** __restrict out_vars);
! 270: /*
! 271: * rpc_cli_ping() - Ping RPC server
! 272: *
! 273: * @cli = connected client
! 274: * return: -1 error or !=-1 ping seq id
! 275: */
! 276: int rpc_cli_ping(rpc_cli_t *cli);
! 277:
! 278:
! 279: /*
! 280: * rpc_cli_openBLOBClient() - Connect to BLOB Server
! 281: *
! 282: * @rpccli = RPC Client session
! 283: * @Port = Port for bind server, if Port == 0 default port is selected
! 284: * return: NULL == error or !=NULL connection to BLOB server established
! 285: */
! 286: rpc_cli_t *rpc_cli_openBLOBClient(rpc_cli_t * __restrict rpccli, unsigned short Port);
! 287: /*
! 288: * rpc_cli_closeBLOBClient() - Close connection to BLOB server and free resources
! 289: *
! 290: * @cli = BLOB Client session
! 291: * return: none
! 292: */
! 293: void rpc_cli_closeBLOBClient(rpc_cli_t ** __restrict cli);
! 294:
! 295:
! 296: /*
! 297: * rpc_cli_openClient2() - Connect to layer2 RPC Server
! 298: *
! 299: * @InstID = InstID for RPC session request
! 300: * @netBuf = Network buffer length (min:512 bytes), if =0 == BUFSIZ (also meaning max RPC packet)
! 301: * @csIface = Interface name for bind client, if NULL first interface on host
! 302: * @csHost = Host ethernet address
! 303: * return: NULL == error or !=NULL connection to RPC server established
! 304: */
! 305: rpc_cli_t *rpc_cli_openClient2(u_char InstID, int netBuf,
! 306: const char *csIface, const char *csHost);
! 307: /*
! 308: * rpc_cli_closeClient2() - Close layer2 connection to RPC server and free resources
! 309: *
! 310: * @cli = RPC Client session
! 311: * return: none
! 312: */
! 313: void rpc_cli_closeClient2(rpc_cli_t ** __restrict cli);
! 314:
! 315:
! 316: /*
! 317: * rpc_cli_openClientExt() - Connect to pipe RPC Server
! 318: *
! 319: * @InstID = InstID for RPC session request
! 320: * @netBuf = Network buffer length (min:512 bytes), if =0 == BUFSIZ (also meaning max RPC packet)
! 321: * @fd = File descriptor
! 322: * return: NULL == error or !=NULL connection to RPC server established
! 323: */
! 324: rpc_cli_t *rpc_cli_openClientExt(u_char InstID, int netBuf, int fd);
! 325: /*
! 326: * rpc_cli_closeClientExt() - Close pipe connection to RPC server and free resources
! 327: *
! 328: * @cli = RPC Client session
! 329: * return: none
! 330: */
! 331: void rpc_cli_closeClientExt(rpc_cli_t ** __restrict cli);
! 332:
! 333:
! 334: #endif
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>