1 /* 2 * Hedgewars, a free turn based strategy game 3 * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com> 4 * 5 * This program is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU General Public License 7 * as published by the Free Software Foundation; either version 2 8 * of the License, or (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 */ 19 20 /* 21 * Low-level protocol support for the IPC connection to the engine. 22 */ 23 #ifndef IPCBASE_H_ 24 #define IPCBASE_H_ 25 26 #include <stddef.h> 27 #include <stdbool.h> 28 #include <stdint.h> 29 30 #define IPCBASE_MAPMSG_BYTES 4097 31 32 typedef enum {IPC_NOT_CONNECTED, IPC_LISTENING, IPC_CONNECTED} IpcState; 33 34 typedef struct _flib_ipcbase flib_ipcbase; 35 36 /** 37 * Start an engine connection by listening on a random port. The selected port can 38 * be queried with flib_ipcbase_port and has to be passed to the engine. 39 * 40 * Returns NULL on error. Destroy the created object with flib_ipcbase_destroy. 41 * 42 * We stop accepting new connections once a connection has been established, so you 43 * need to create a new ipcbase in order to start a new connection. 44 */ 45 flib_ipcbase *flib_ipcbase_create(); 46 47 /** 48 * Return the listening port 49 */ 50 uint16_t flib_ipcbase_port(flib_ipcbase *ipc); 51 52 /** 53 * Free resources and close sockets. NULL safe. 54 */ 55 void flib_ipcbase_destroy(flib_ipcbase *ipc); 56 57 /** 58 * Determine the current connection state 59 */ 60 IpcState flib_ipcbase_state(flib_ipcbase *ipc); 61 62 /** 63 * Receive a single message (up to 256 bytes) and copy it into the data buffer. 64 * Returns the length of the received message, a negative value if no message could 65 * be read. 66 * 67 * The first byte of a message is its content length, which is one less than the returned 68 * value. 69 * 70 * Note: When a connection is closed, you probably want to call this function until 71 * no further message is returned, to ensure you see all messages that were sent 72 * before the connection closed. 73 */ 74 int flib_ipcbase_recv_message(flib_ipcbase *ipc, void *data); 75 76 /** 77 * Try to receive 4097 bytes. This is the size of the reply the engine sends 78 * when successfully queried for map data. The first 4096 bytes are a bit-packed 79 * twocolor image of the map (256x128), the last byte is the number of hogs that 80 * fit on the map. 81 */ 82 int flib_ipcbase_recv_map(flib_ipcbase *ipc, void *data); 83 84 /** 85 * Blocking send bytes over the socket. No message framing will be added. 86 * Returns 0 on success. 87 */ 88 int flib_ipcbase_send_raw(flib_ipcbase *ipc, const void *data, size_t len); 89 90 /** 91 * Write a single message (up to 255 bytes) to the engine. This call blocks until the 92 * message is completely written or the connection is closed or an error occurs. 93 * 94 * Calling this function in a state other than IPC_CONNECTED will fail immediately. 95 * Returns 0 on success. 96 */ 97 int flib_ipcbase_send_message(flib_ipcbase *ipc, void *data, size_t len); 98 99 /** 100 * Try to accept a connection. Only has an effect in state IPC_LISTENING. 101 */ 102 void flib_ipcbase_accept(flib_ipcbase *ipc); 103 104 #endif /* IPCBASE_H_ */ 105 106